Welcome to mirkes.de&'s Tiny Hexer

This help file contains information about Tiny Hexer, a free binary file editor by mirkes.de.
  • Introduction
  • Frequently asked questions
  • The main window
  • The editor window
  • Structure viewer
  • Value editor
  • Tiny Hexer Script
mirkes.de's Tiny Hexer, Copyright ©2003-2004 Markus Stephany. All rights reserved.


Introduction to Tiny Hexer

Here you can find some basic information about Tiny Hexer.
  • Features
  • License
  • Credits
  • About the author
  • Version history

Features

  • Search and replace of text or hex bytes (also with wildcard byte and regular expressions)
  • File statistics and graphical data representation
  • Editable file size up to 2 GB (depends on available virtual memory)
  • Native 32 Bit Windows application, MDI
  • Ascii, Ansi, EBCDIC (Codepage 38), Mac and custom character conversion
  • Scripting engine (Tiny Hexer Script language)
  • Insert and delete half bytes (nibbles or nybbles)
  • Insert, Overwrite and Readonly modes
  • Common bookmarks and keyboard bookmarks per file
  • Unicode support (character display, search and replace)
  • Cutting and pasting of binary data (also Zero bytes)
  • Automatic backups of modified files
  • Configurable keyboard, shortcuts and toolbar
  • Value editor to modify bytes, words, IEEE floating point numbers, single bits...
  • Structure viewer to better understand file structures (with sample structure scripts for .bmp, .exe and .zip files)
  • Multiple Undo, single Redo capabilities
  • OLE Drag 'n' Drop support
  • Disk editing (Windows NT/2000/XP only)
  • Modifying of other processes' memory
  • Configurable editor appearance
  • Save and reload sets of options
  • Scriptable file import and export (with sample import scripts for hex text, Intel hex and Motorola S-record and sample export scripts for c-source file, pascal-source file, hex text, Intel hex and Motorola S-record)
  • Absolutely free of charge!
  • and more...

License

mirkes.de's Tiny Hexer ("the software") license agreement:

by unpacking or running any application from this package, you agree to be
bound by and are becoming a party to this agreement. if you do not agree to
all of the terms of this license agreement, you must destroy the package.

markus stephany ("the author") grants you a non-exclusive license to use the
software free of charge.

this agreement shall be interpreted in accordance with the laws of the
federal republic of germany without application of that states choice of law
provisions. any actions arising from this license or the use of this
software shall be commenced and maintained in the brd (frg).

* limitations on installation and use of the software:

you may lend or copy and distribute the software free of charge to other
people provided always that the terms and conditions of this agreement
accompany to each copy so lent or distributed.

you must not charge a fee, exchange goods or services, barter or otherwise
profit in a commercial way from the lending, leasing, selling or
distribution of the software.

you may not modify, translate, reverse engineer, decompile, dissassemble any
part of the software or create derivative works based on the software.

* disclaimer of warranty:

this software is provided "as is" without warranty of any kind, either
expressed or implied, including, but not limited to the implied warranties
of merchantability and fitness for a particular purpose. the entire risk as
to the quality and performance of this software is with you. should the
software prove defective, you assume the entire cost of all necessary
servicing, repair, and correction.

the author does not warrant that the functions contained in the software
will meet your requirements or that the operation of the program will be
uninterrupted or error free.

under no circumstances and under no legal theory, tort, contract, or
otherwise, can the author be liable to you or any other person for any
indirect, special, incidental, or consequential damages of any character
including, without limitation, damages for loss of goodwill, work stoppage,
computer failure or malfunction, or any and all other commercial damages or
losses. in no event will the author be liable for any damages in excess of
the amount the author received from you for a license to the software, even
if the author should have been informed of the possibility of such damages,
or for any claim by any other party. this limitation of liability shall not
apply to liability for death or personal injury to the extent applicable law
prohibits such limitation. furthermore, some jurisdictions do not allow the
exclusion or limitation of incidental or consequential damages, so this
limitation and exclusion may not apply to you. no dealer, agent, or employee
of the author is authorized to make any modifications, extensions, or
additions to this warranty.

title, ownership rights, ownership of all derivative works, and intellectual
property rights in the software remain with the author. the software is
protected by copyright and other intellectual property laws and by
international treaties. title and related rights in the content accessed
through the software is the property of the applicable content owner and may
be protected by applicable law. this license gives you no rights to such
content.

* termination of the license

the license will terminate automatically if you fail to comply with the
limitations described herein. on termination, you must destroy all copies of
the software and documentation. your obligations to pay accrued charges and
fees shall survive any termination of this agreement.

* acknowledgement

you acknowledge that you have read this agreement, understand it and agree
to be bound by its terms and conditions. you further agree that it is the
complete and exclusive statement of the agreement between yourself and the
author.

Credits

Search for regular expressions is based on the Regex Library by Niche Software.
Note: I modified the original code to (hopefully) work with different character sets and unicode files. After some (little) testing I decided to use the code I modified in Tiny Hexer. Please inform me if searching for regular expressions does not work as expected. Do not blame the author of the original library for possible mistakes in my derivative implementation!

Boyer-Moore-Horspool search algorithm based on Angus Johnson's TSearch Delphi VCL.
Note: I modified the original code to work with wildcards. After successful testing, I decided to use this modified code. Please inform me if searching does not work as expected. To disable the new searching algorithm, see the FAQ.

Windows XP Themes support by Mike Lischke's TThemeManager Delphi VCL.

The scripting engine has been written using a derivative of the unit expression.pas found on http://www.blacky.co.nz/free/index.htm.

HTML Help support by Delphi units written by The Helpware Group.

The SHELL() function is based on the unit ConsoleApp.pas by Martin Lafferty.

The editor is a special version of my component TMPHexEditorEx, available at http://www.mirkes.de/en/delphi/vcls/hexedit.php. Many people helped me with this component, so credits go to John Hamm, Christophe Le Corfec, Philippe Chessa, Daniel Jensen, Shmuel Zeigerman, Vaf, Eugene Tarasov, FuseBurner, Motzi, Martin Hsiao and others.

The graph in the Statistics Window is drawn using the free TMathImage component by Renate Schaaf.

RTF Export is based on the unit Ctltortf.pas by K. Nishita.

The setup is created using Jordan Russell's famous Inno Setup and Bjørnar Henden's ISTool.

Executable file's sizes are shrinked using Jordan Russell's StripReloc (no "Exe compressor"!).

Unicode enabled Value Editor using TNT Delphi Unicode Controls by TNT Software Products.

About the author

This free binary file editor has been written by Markus Stephany, 66679 Losheim am See, Saarland, Germany. It is written using Borland Delphi™ 6 Professional. You can reach Markus via EMail at mailto:tinyhexer@mirkes.de.

Version history

  • 1.0.1.29, June 16, 2004:

    • Fixed an exception in the File statistics window when only a few bytes of data were used
    • Fixed missing icons in the Window Bar
    • Fixed wrong separator width after customizing the Tool Bar buttons
    • The Window Bar is now displayed only when two or more files are opened
    • The Ruler now displays numbers using the current Editor Offset Format
    • The caret is set to a bottom line in No Editing mode
    • The File statistics window supports more data types
    • The Editor Offset Format can be adjusted independently for each open file
    • Rearranged View and Options menu
    • Split the Options dialog into a global and an editor specific options dialog
    • View/Synchronize command added
    • Tools/Compare/Compare command changed to synchronize the view of the compared editors
    • The Value Editor now can also display and edit 16 bit unicode characters (NT platforms only)

  • 1.0.1.27 - 1.0.1.28, June 07, 2004:

    • Fixed some drawing bugs
    • Using the mouse wheel scrolls a page rather than a single line
    • Implemented a Window Bar
    • The scrollbars in editor windows have proportional thumbs now
    • Added an option to configure default Insert/Overwrite mode

  • 1.0.1.26, May 30, 2004:

    • Fixed a bug that caused all files to be opened read-only
    • The "Copy" popup menu command in the Structure Viewer now (hopefully) works
    • Printing the Structure Viewer contents now produces more meaningfull page headers and footers
    • Fixed some minor format strings related bugs

  • 1.0.1.25, May 16, 2004:

    • Added in Tiny Hexer Script: ERRORHANDLER, ERRORLINE, ERRORMESSAGE, ERRORNUMBER, IFGOTO

  • 1.0.1.24, May 09, 2004:

    • Fixed a bug that could raise an error message when starting another instance of Tiny Hexer while the previous instance was terminating
    • Slightly modified the format of configuration files (but still backward compatible)
    • Added an option to force maximized creation of new editor windows

  • 1.0.1.23, May 05, 2004:

    • When loading settings from a file, tiny hexer now searches for a specific value in the configuration file. If this value is not found, a warning is displayed (to distinguish Tiny Hexer config files from other .ini-files which could mess up the Tiny Hexer registry key).
    • Tiny Hexer isn't associated with all file types anymore (see the FAQ for details)
    • Tiny Hexer can now be forced to load a default configuration file at startup (see the FAQ for details)

  • 1.0.1.22, May 02, 2004:

    • Hopefully fixed a possible bug ("Invalid property value") on startup (Problem was reported anonymously without enough details)
    • The "File/Open Group" command can get cancelled using the ALT or ESC key
    • Fixed active editor window if the "File/Open Group" command shows an error message
    • Removed some stuff from the small edition (toolbar configuration, images, keyboard mapping, configurable menu shortcuts, start/stop-script) to further reduce its size and resource usage

  • 1.0.1.21, May 01, 2004:

    • Shrunk the size of Tiny Hexer small edition
    • The "Open in Tiny Hexer" shell context menu could lead an already running instance of Tiny Hexer to hang if it was showing a modal dialog

  • 1.0.1.20, Apr. 28, 2004:

    • Fixed a bug that brought up an error message when resizing the "File/Statistics" window
    • An error message is now displayed when some files couldn't get opened via drag and drop
    • Added the "File/Open Group" and "File/Save Group" commands

  • 1.0.1.19, Apr. 25, 2004:

    • The "File/Open" command now allows to open multiple files at once
    • Added the "File/Reload" command
    • Added the "File/Statistics" command
    • Added the ability to search for regular expressions
    • The Position List and per-file-bookmarks do store selections, not just positions
    • Position 0 can now get bookmarked
    • Fixed a bug that caused Tiny Hexer to forget the Find Dialog's settings
    • Fixed a bug that caused Tiny Hexer to crash when editing bookmarks

  • 1.0.1.18, Jan. 11, 2004:

    • "Insert Nibble" and "Delete Nibble" commands disabled in fixed filesize mode

  • 1.0.1.17, Dec. 24, 2003:

    • Added a Position list window
    • Added in Tiny Hexer Script: AbsolutePosition, AbsoluteSize, ASKFINDOPTIONS(), POSITIONS(), POSITION_ADD(), POSITION_COUNT(), POSITION_DESC, POSITION_SELECTED(), CMD.EditFindStore, CMD.PosListDeleteSelected, CMD.PosListLoad, CMD.PosListSave, CMD.PosListSelectAll, CMD.PosListShiftSelected, CMD.ToolsPosList
    • Added a "Find All and Store" command to the Edit Menu
    • Added Help menu commands for direct access to version history and the Tiny Hexer Script reference
    • Added a "Print" command in the Structure viewer
    • The status bar panels are now sized automatically
    • Some commands (like "Find Next") sometimes were not available when they should have been
    • Some other minor code fixes

  • 1.0.1.16, Dec. 16, 2003:

    • Changing a data file's size via script is undoable now
    • "Fixed file size" option cannot be changed when editing disk sectors or process memory
    • The statusbar now shows whether a file's size is fixed or not
    • Two file properties added: FillByte and FixedSize
    • Script for file resizing added

  • 1.0.1.15, Dec. 10, 2003:

    • Fixed a bug when doublecklicking the ruler bar (sometimes line 0 -1 has been displayed)

  • 1.0.1.14, Dec. 07, 2003:

    • Removed some code from the small edition, so it is even smaller now
    • On closing editor windows containing unsaved changes, Tiny Hexer know displays the correct dialog when editing disk data or process memory blocks (not just the "Save As" dialog)

  • 1.0.1.13, Nov. 29, 2003:

    • The new search algorithm now also works in unicode mode
    • If the Open process dialog's hex editor is in unicode mode, the process range will be opened in tiny hexer in unicode mode automatically
    • Changed behaviour of shortcuts, so shortcuts like 'CTRL+C' work in non modal active windows

  • 1.0.1.12, Nov. 27, 2003:

    • Faster searching by using a Boyer-Moore-Horspool algorithm
      Note: I modified the original algorithm to work with wildcards. After successful testing, I decided to use this modified code. Please inform me if searching does not work as expected. To disable the new searching algorithm, see the FAQ.
    • During disk editing, the absolute address on disk is also displayed on the status bar
    • Bookmarks now store absolute disk addresses
    • "Goto Sector" in the disk menu renamed to "Goto Sector/Position", now byte based absolute disk positions can be entered in this dialog
    • The wildcard in the Find dialog now can be typed as a character, not only a hex value
    • Some more drawing bugs on themed XP fixed
    • More settings are now saved when using the "Options/Save Settings" command (file settings, search/replace history...)

  • 1.0.1.11, Nov. 23, 2003:

    • Improved Windows XP themes support
    • Some other GUI fixes
    • Search/replace can be cancelled by pressing the ALT key
    • More than 4096 disc sectors can be read at once
    • Whole partitions/volumes can be searched for data
    • A default value for disk sectors to be read at a time can be set
    • Progress bar during search/replace

  • 1.0.1.10, Nov. 15, 2003: the Drive/Partition dialog now allows you to show more than one single sector at once in the hex editor window.
  • 1.0.1.9, Oct. 24, 2003: changed the Drive/Partition dialog's list to display a horizontal scroll bar if necessary.
  • 1.0.1.8, Oct. 17, 2003: added TEXTCHOP() function, added commands to compare two open files
  • 1.0.1.7, Oct. 14, 2003: somewhat faster scripting engine, added output parameter to the SHELL() function, added TEXTBOX command
  • 1.0.1.0 - 1.0.1.6: some minor bugs fixed, german language user interface added.


Frequently asked questions

Frequently asked question (FAQ)

On this page some frequently asked questions about Tiny Hexer are answered.

Bugs:

Bugs already fixed in Tiny Hexer are listed in the version history.

General:

How can I prevent files from being opened in Tiny Hexer when accidentally doublecklicking them in Explorer?

By default, Tiny Hexer up to version 1.0.1.22 associates itself with all file types, but not as the standard application. File types not having any standard association will possibly be opened in Tiny Hexer if they are doubleclicked in Explorer. To disable this behaviour, download and execute this .reg-file.

Note: As of version 1.0.1.23, a fresh installation doesn't associate all file types with Tiny Hexer but creates a shortcut in the "Send To" context menu of Explorer. WebUpdate installations (from the Help menu in Tiny Hexer) do not create the shortcut in the "Send To" context menu.

How can I prevent Tiny Hexer from creating an unnamed editor window?

There are two ways to start Tiny Hexer without showing an empty document window:

  • Start Tiny Hexer using the /n command line switch.
  • Close Tiny Hexer. Then download and execute this .reg-file to permanently prevent Tiny Hexer from showing that untitled window at startup. Note: This only works in version 1.0.1.12 and higher.

Tiny Hexer Small Edition:

Tiny Hexer settings cannot get exported properly by regedit, so i cannot use predefined settings with BartPE!

Unfortunately, regedit is not able to export REG_SZ values containing line ending characters (CR, LF) properly, so such .reg-files cannot be imported successfully again. I'm currently thinking of using a different registry type (e.g. REG_BINARY), but that will pose some problems concerning the configuration management code in Tiny Hexer.

As of version 1.0.1.23, there exists a workaround: If you create a REG_SZ value "LOAD_INI"="1" under the HKEY_CURRENT_USER\Software\mirkes.de\Tiny Hexer\1.0\_\ registry key, Tiny Hexer is forced to load its settings from the configuration file mpth_small.ini (in the small edition; mpth.ini in the full version) at startup. This .ini file must be located in Tiny Hexer's program folder. To create such a configuration file, use the "Options/Save Settings" command in Tiny Hexer (use the full version to create the settings file if possible, it does store more settings). The distribution package of Tiny Hexer Small Edition includes an example (look at mpth_small.inf and mpth_small.ini).

Tiny Hexer Small Edition does not start on WinPE!

There is a bug in version 1.0.1.11 of mpth_small.exe which prevents it from working under WinPE. Please upgrade to the latest version.

Searching:

The new fast search algorithm does not work as expected!

The new faster Boyer-More-Horspool based search algorithm introduced in Tiny Hexer 1.0.1.12 is based on an efficient code not written by me. I had to modify this code to use wildcard characters. Since i'm not a mathematician, i hardly understand the algorithm and might have done a mistake in my implementation. If the algorithm should not work as expected, please inform me! To disable this fast search algorithm, close Tiny Hexer, then download and execute this .reg-file and restart Tiny Hexer.

Note: The new search algorithm did not work in unicode mode in version 1.0.1.12. This bug has been fixed in version 1.0.1.13.

Disk editing:

How can I write changes made on disk sectors back to the drive?

Since this command might be quite dangerous (Tiny Hexer does not lock disks, so you may overwrite disk data modified by the operating system or other applications), it is not available by default. You can enable the disk writing feature by downloading and executing this .reg-file. After restarting Tiny Hexer, the "File/Disk/Write Changes" menu command should be available.

What are the differences between sectors, absolute disk positions and caret positions?

Tiny Hexer cannot operate on a whole drive or partition for the time being, so you have to load a part of the disk's data into memory to edit that data.
Disk data is stored in sectors, each volume has a specific sector size. Usually hard disk volumes have a sector size of 512 byte, CDRoms' sectors contain 2048 byte of data.
So if you open a hard drive volume and select an amount of 16 sectors at once, 16*512=8192 byte of disk data are displayed at once in the editor.

Using the "File/Disk/Goto Sector/Position" menu command you can either navigate to a specific sector or an absolute position. If you choose an absolute position, the sector representing this position is loaded into the editor and the editor's caret will be set to the position relative to the sector that matches the selected absolute position.
An example: Choosing the absolute position 4711 on a hard disk (sector size 512 byte) will load sector 9 into the editor and set the caret to offset 103 as 4711 divided by 512 results in 9 (sector) and 4711 modulo 512 results in 103 (offset).


Regular Expressions

On this page I will try to explain the regular expression based search in Tiny Hexer.
  • Overview
  • Definitions
  • Notes

Overview

You can choose to use Regular Expressions in Tiny Hexer's Find/Replace window to perform powerful searches. If you ever tried the wildcards "*" or "?" in a directory listing (like "dir *.txt"), you already have used a simple form of regular expressions.

Regular expressions in Tiny Hexer, however, can be much more powerful than those filename wildcards.

Imagine the following: There's a binary file containing address records, but it's corrupted somehow and cannot be opened anymore in the address book application. Now you need the address of a Mr. Johnson, Jonson, Jenssen or is it Jensen? Unfortunately you are not sure about the exact name, and you cannot find his address anywhere else. But you know that the record is stored in this binary address record file. After loading this file into Tiny Hexer you could do sequential searches for all those names in the data, but what if he's called Jehnsen or Jonnsen? Using the regular expression J[oe]h?n+s+[oe]n you can search for all these names at once.

Well..., how does it work? I'll try to answer this question in the following section.

Definitions

Regular expressions are sets of elements used to match patterns of data, that is each element (character, set or group) in a regular expression can match none, one or more characters or groups of characters (depending on branches and modifiers).

Characters

The simplest element is an ordinary character ("a", "b"...). This element matches exactly that character in the data. In the example above the character J is used to find the first character of the name (Johnson, Jensen...). Character elements can be written in hexadecimal form by being prefixed with the \x escape to allow searching for binary data (e.g. \x0A for the character with the binary value of 0A hex = 10 dec). Some characters that have a special meaning in regular expressions must be escaped using the backslash \ (unless they are written in hexadecimal notation), those characters are ., *, \, +, (, ), ?, |, [ and ].

Sets

Sets are used to match either one of the characters included in the set. In the example above, the set [oe] is used to match either the character "o" (Jon.../...son) or the character "e" (Jen.../...sen). Sets are embedded in brackets ([...]).You can include ranges of characters in sets by writing a hyphen between the first and the last value, e.g. to match alphanumerical characters, you may write [0-9a-zA-Z]. You can also use negated sets by putting the circumflex (^) after the opening bracket: If you want to search for any data except alphanumerical characters, you may write [^0-9a-zA-Z].

The following predefined sets exist (they do not need to be embedded in brackets):

  • "." matches any value (00 hex - FF hex)
  • "\a" matches any alphabetic character ('a' - 'z' and 'A' - 'Z')
  • "\d" matches any digit ('0' - '9')
  • "\w" matches any alphanumerical character ('a' - 'z', 'A' - 'Z' and '0' - '9')

Groups

Groups connect sequences of elements. They are used in conjunction with modifiers and branches (see below). Element groups are embedded in parentheses ((...)). So if you want to search for either "John" or "Jane", use the regular expression (John|Jane), if you want to search for either "John" or "Jonny", you might use Joh?n(ny)?.

Branches

Branches allow to search for either one of alternatives of groups or elements. They work like logical ORs. All elements of a branch have to be separated by a pipe character (|). So if you want to search for either "John Smith", "John Taylor" or "John Q Public", you can use the regular expression John (Smith|Taylor|Q Public).

Modifiers

Modifiers tell the matcher how often the preceding group, element or set must occur in the data.

The following modfiers exist:

  • "*" the preceding group, element or set might be present any time (also zero times), e.g. Jon*y matches "Joy", "Jony", "Jonny" and "Jonnny".
  • "?" the preceding group, element or set might be present one time (also zero times), e.g. Jon?y matches "Joy" and "Jony", but not "Jonny" or "Jonnny".
  • "+" the preceding group, element or set must be present at least one time, e.g. Jon+y matches "Jony", "Jonny" and "Jonnny", but not "Joy".

The modifier ? has a different meaning if it's the first character in the regular expression: It tells the matcher to be "non-greedy", that is the modifiers "eat" as little characters as possible to match the pattern. An example: The pattern T.+s finds "This is" in the text "This is a text", the pattern ?T.+s just finds "This".

Notes

  • The search for regular expressions is based on the Regex Library by Niche Software.
    I modified the original code to (hopefully) work with different character sets and unicode files. After some (little) testing I decided to use the code I modified in Tiny Hexer. Please inform me if searching for regular expressions does not work as expected. Do not blame the author of the original library for possible mistakes in my derivative implementation!
  • In contrast to the usual behaviour of the . set in regular expressions, the Tiny Hexer version matches all data values, not only alphanumerical characters.
  • The common regular expression modifiers ^ (match line start) and $ (match line end) are not correctly implemented in my modified version of the regular expression library and thus should be avoided.
  • When searching in unicode files, sets do not work if they contain characters with an unicode value > 00ff hex, e.g. [€¢] will not match the Euro sign. In this case you should rather use grouped branches: (€|¢)
  • There might be further problems with matching regular expressions if the data file is in unicode format or in a character set other than Windows ANSI. This is due to some quick 'n' dirty hacks i made in the RegEx library derivative used in Tiny Hexer.


Main window

This topic briefly explains the menus and controls in the main window.
  • The menu
  • The toolbar
  • The window bar
  • The status bar

The menu

  • File menu
  • Edit menu
  • View menu
  • Tools menu
  • Options menu
  • Bookmark menu
  • Window menu
  • Help menu

The toolbar

The toolbar gives you quick access to some of the menu commands. You can customize the buttons on the toolbar by doublecklicking an unoccupied part of the toolbar or using the Options/Customize Toolbar command.

The window bar

The window bar displays a tab for each editor window. By left clicking a tab, the corresponding editor window is activated, by right clicking a tab, the system menu of the editor window is displayed. The visibility of the window bar can be toggled using the View\Show Window Bar command.

The status bar

The statusbar consists of nine segments:

  1. The first segment displays the size of the file in the active editor
  2. The second segment displays the current caret position in the active editor window. If a range of disk sectors is currently being edited, the absolute address on disk the caret is pointing to is also displayed (in parenthesis)
  3. The third segment shows the start and end position of a selected block
  4. The fourth segment shows an asterisk (*) if the active file has been modified
  5. The fifth segment shows an "R" if the active file has been opened readonly
  6. The sixth segment shows an "F" if the active file's size is fixed (when editing disk sectors or process memory blocks or when it has been configured in the Options Dialog)
  7. The seventh segment tells you if Insert (INS) or Overwrite (OVW) mode is active
  8. The eighth segment tells you the current character translation mode (like ANSI (WIN), EBCDIC (BCD) and so on)
  9. The last segment is a multiple purpose field, it shows hints and load/save/script progress


File menu

This topic describes the commands in the File Menu.
  • New: Open a new, empty Editor window
  • Open: Select one or more files in a dialog and open them in Tiny Hexer
  • Reopen: This submenu contains a list of previously used files; by clicking an entry the file is opened in a new editor window
  • Reopen/Cleanup: Remove non-existing files from the Reopen menu
  • Insert File: Insert a file from disk at the current position in the active editor window. If a block of data is currently selected, this block will be replaced by the file's data
  • Reload: Discard all changes and reload the current file from disk again
  • Open Group: Open a group of files previously stored using the following command
  • Save Group: After selecting a group of open files in a dialog, this group is stored in a file. Using the previous command all files in this group can be opened again later
  • Disk: This submenu contains commands to work with raw data on disk partitions, CD-Roms and Floppy Disks (Windows NT/2000/XP only)
  • Process: This submenu contains commands to read and write memory in other processes:

    • Read Process Memory: Displays the Read Process Memory dialog, where you can select a memory block in another process to be opened in Tiny Hexer
    • Write Process Memory: After modifying a process memory block in the editor, you can write back the data to the other process. The Write Process Memory dialog is displayed to choose some options. This is a dangerous command as you might crash the process. If you write nonsense data to a system process, the whole system might crash!

  • Save: Save a modified file back to disk. Automatic backups can be configured in the Global Settings dialog (auto backups are enabled by default)
  • Save As: Save the active file under a different name
  • Save Selection: Save the selected data block to a file on disk
  • Import: Select a file in a specific format (e.g. hex text) and choose the file type in the Import dialog to open the data file in a new editor window
  • Export: Save the current file in a specific format (e.g. hex text) after selecting the export type in the Export dialog
  • Print Setup: Show the Windows Printer Setup dialog to select a printer
  • Print: Open the Print Preview window to print the current file
  • Statistics: Display some statistical data for the current file or selection in the File Statistics window
  • Close: Close the active editor window
  • Close All: Close all open editor windows
  • Exit: Leave Tiny Hexer


File/Disk menu

This topic describes the commands in the File/Disk Menu (Windows NT/2000/XP only, you might need administrative privileges to gain direct access to drives).
  • Open Drive: Displays the Drive/Partition dialog, where you can select a physical drive, a disk partition, a CD Rom or a Floppy Disk that is displayed sector by sector in an hex editor window
  • Load First Sector: Loads the first sector of the opened drive, partition or media into the editor window
  • Load Previous Sector: Loads the previous sector of the opened drive, partition or medium into the editor window
  • Load Next Sector: Loads the sector following the current one into the editor window
  • Load Last Sector: Loads the last sector of the opened drive, partition or medium into the editor (Note: Sometimes the sector calculation routine seems to calculate less sectors than a partition actually has. To access those missing sectors, use the Goto Sector command)
  • Goto Sector/Position: Here you can enter a disk/partition sector number that should be opened in the editor. This number may be prefixed by a minus "-" or plus "+" sign to enter a sector range relative to the current sector or by a greater than sign ">" to enter an amount of sectors relative to the last sector.

    You may also enter an absolute position on disk (byte based, not sector based) by prefixing the value by an exclamation mark "!".
  • Write Changes: After modifying a sector in the editor, you can write back this changed sector to disk. (This command is not available by default as it can be very dangerous. Tiny Hexer does not lock the sectors being edited, so Windows might modify the disk sector after loading it into Tiny Hexer. In this case writing back the sector to disk leads to inconsistent disk data and might damage the whole filesystem! To enable this command, you will have to add a string value to the registry, Name "***DISK_WRITING***", Value "***DISK_WRITING***" in the key [HKCU\Software\mirkes.de\Tiny Hexer\<version>\fmTinyHexer1Main]. Use this command absolutely at your own risk, you have been warned!!!)


Edit menu

This topic describes the commands in the Edit Menu.
  • Undo: Undo modifications
  • Redo: Reapply the latest undone modification
  • Copy: Copy the current selection to the clipboard
  • Cut: Cut the current selection to the clipboard
  • Paste: Paste clipboard contents into the active document. If the clipboards contains third party data, a dialog will be shown which allows you to select the data type
  • Select All: Select all data in the active document
  • Goto: Shows a dialog where you can type a position to set the cursor to in the active document. This number may be prefixed by a minus "-" or plus "+" sign to enter a position relative to the current cursor position or by a greater than sign ">" to enter a position relative to the file's end
  • Select: Shows a Selection dialog where you can enter a block of data to be selected
  • Store in Position List: Adds the current cursor position/selection to the Position List
  • Insert Nibble: Inserts half a byte (4 Bits=1 Nibble) at the current cursor position into the document (so all data behind the cursor position is shifted 4 Bits to the right)
  • Delete Nibble: Deletes half a byte (4 Bits=1 Nibble) at the current cursor position in the document (so all data behind the cursor position is shifted 4 Bits to the left)
  • Find/Replace: Opens the Find/Replace window to search for hex bytes or text in the active document. You can also replace data using this window. Find and replace processes can be cancelled by pressing the ALT key.
  • Find All and Store: Shows a Find dialog where you can select text or data to search for. After clicking the "Find" button in this dialog, all occurences in the active document will be found and stored in the Position List.
  • Find Next: Continue searching for text/data
  • Convert: Opens the Convert dialog that allows you to convert the current selection/document from one charset to another (e.g. from Windows to EBCDIC)


View menu

This topic describes the commands in the View Menu.
  • Character Translation
  • Character Translation: Unicode
  • Editor Offset Format
  • No Editing
  • Number Format
  • Show Window Bar
  • Synchronize

Character Translation

With these commands you can switch between different character translations. These translations are used to convert characters from one charset to another when displaying and typing them in the character pane of the editor windows. The Edit/Find and Edit/Replace commands also are affected by the character translation when searching for text.

  • Windows: Do not convert characters (used to edit files containing Ansi text data)
  • Dos 8 Bit: Use it to edit files containing text in DOS charset
  • ASCII 7 Bit: Use it to edit 7 Bit ASCII files
  • Macintosh: For editing files containing Macintosh™ text
  • EBCDIC Codepage 38: For files in EBCDIC character set
  • Custom Translation: For files in other formats, you can edit the conversion tables using the Custom Character Translation table dialog

Unicode

In Tiny Hexer it is possible to display Unicode text, also basic editing of Unicode characters is supported. Switching to Unicode mode also affects the Edit/Find and Edit/Replace commands. In Unicode mode, no single bytes can be selected, deleted or inserted, only whole unicode characters are editable (each Unicode character consists of two bytes).

  • Unicode (Little Endian): Use it to edit little-endian unicode files
  • Unicode (Big Endian): Use it to edit big-endian unicode files

Editor Offset Format

These commands allow you to change the format of the offset display (the leftmost part of the editor windows).

  • Hexadecimal: Show cursor offsets in hexadecimal (16 based) notation
  • Decimal: Show cursor offsets in decimal (10 based) notation
  • Octal: Show cursor offsets in octal (8 based) notation
  • None: Don't show cursor offsets

No Editing

After switching to "No Editing" mode, the affected editor window acts as a file viewer only, the data isn't editable any longer.

Number Format

These commands allow you to change the format of numbers displayed on the status bar.

  • Hexadecimal: Show numbers in hexadecimal (16 based) notation
  • Decimal: Show numbers in decimal (10 based) notation
  • Octal: Show numbers in octal (8 based) notation

Show Window Bar

Using this command, you can toggle the visibility of the Window Bar.

Synchronize

This command allows you to synchronize cursor position, view and selection of two editor windows, i. e. if you change the position in one editor, it is automatically changed in the second editor too. This feature is particulary useful when comparing the contents of two files. When switching on synchronization, you can choose the second editor window from a dialog. You can also specify a position offset (e. g. if you select an offset of 400, the cursor in the second editor is set to the position of the first editor + 400). Use the Shift+Tab keys to quickly switch between the two syncronized editors. Synchronization can be turned off by using this command again.


Tools menu

This topic describes the commands in the Tools Menu. You can add custom tools to this menu by using the Configure Tools command.
  • Compare
  • Configure Tools
  • Structure Viewer
  • Value Editor
  • Position List
  • Execute Script

Compare

The commands in the Tools/Compare submenu allow you to compare the contents of the current editor data/selection to a file on disk and highlight the differences (showing different bytes in a user defined color in the editor).

  • Compare to file: Select a file on disk and compare its data to the whole data in the active document. After comparison Tiny Hexer will tell you whether data and/or file sizes differ and colorize different bytes in the editor
  • Compare Selection to file: Select a file on disk and compare its data to the currently selected block in the active document
  • Compare: Select another editor and compare its data to the whole data in the active document. After comparison Tiny Hexer will tell you whether data and/or file sizes differ, colorize different bytes in the editors and enable synchronization of the editors' views
  • Compare Selection: Select another editor and compare its data to the currently selected block in the active document
  • Previous: Select the previous block of differences. A block is a consecutive range of different bytes.
  • Next: Select the following block of differences
  • Reset: Reset comparison data (switch off)
  • Highlight Differences: Switch colorization of different bytes on or off

Configure Tools

Add custom commands to the Tools menu by using the Edit Tools dialog.

Structure Viewer

Show or hide the Structure Viewer, a tool that can help understanding the structure of a file by running a Tiny Hexer Script over the file data and displaying the structure in textual format (e.g. in C language "struct" format).

Value Editor

Show or hide the Value Editor, a tool to edit single Bits, Words, Long Words, IEEE floating point numbers and more.

Position List

Show or hide the Position List, a tool to store and display file positions for quick navigation.

Execute Script

Open an execute a Tiny Hexer Script.


Options menu

This topic describes the commands in the Options Menu.
  • Global Settings: Display the Global Settings dialog to change global options
  • Editor Settings: Display the Editor Settings dialog to change options of editor windows
  • Custom Character Translation Table: Displays the Edit Character Translation dialog to create your own character conversion table
  • Load Saved Settings: Reload a previously saved set of settings
  • Save Settings: Save the current settings to disk to reload and use them later
  • Customize Toolbar: Display the Customize Toolbar dialog to change the commands available on the toolbar


Bookmarks menu

This topic describes the commands in the Bookmarks Menu.

Tiny Hexer supports two kinds of bookmarks:

  • Per-File-Bookmarks
  • All-Files-Bookmarks

Per-File-Bookmarks are explained in the Keyboard section of the Editor window topic.

All-Files-Bookmarks apply to all open editor windows. They store the current selection and whether the cursor is located in the hex or character pane. These bookmarks can have descriptive names. Bookmarks appear at the bottom of the Bookmarks menu.

When editing disk sectors, a bookmark does not store the current caret position but the absolute position on disk the caret is pointing to.

  • Edit Bookmarks: Shows the Edit Bookmarks dialog, where you can delete, rearrange and modify each existing bookmark
  • Add Bookmark: Add a bookmark that stores the current cursor position and selection count. You will be asked to enter a name for the new bookmark


Window menu

This topic describes the commands in the Window Menu.
  • Cascade: Cascade all visible editor windows
  • Tile Horizontally: Tile all visible editor windows horizontally
  • Tile Vertically: Tile all visible editor windows vertically


Help menu

This topic describes the commands in the Help Menu.
  • Index: Opens this help file
  • About: Displays some information about Tiny Hexer


Editor window

This topic briefly explains the Editor window.
  • The Editor
  • Keyboard support
  • Mouse support

The Editor

Each editor consists of different parts (the appearance and existance of some of them may vary depending on Tiny Hexer's settings):

  1. Ruler Bar: This is the uppermost part of the editor window, it shows the byte index of each hex or character data. the current cursor column is highlighted (here: "0203")
  2. Offset Pane: This part displays the data offset of each row, the current row is highlighted (here: "0x72170")
  3. Hexadecimal Field: This field shows the file data byte values in hexadecimal notation. You can insert/overwrite bytes (depending on the active mode), bytes may be arranged in columns of specific widths. Even and odd columns can have different colors.
  4. Character Field: This field shows the file data values as characters. You can insert/overwrite characters (depending on the active mode). Characters can be displayed using different conversion tables. In Unicode mode each character represents two bytes in the Hex field.
  5. Per-File-Bookmark: This "2" sign shows that a per file bookmark (No #2) is set in this row (see the Keyboard section)
  6. Cursor Position: A blinking cursor tells you the current position in the file. In Insert mode the cursor is a single line, in Overwrite mode it is a block covering a whole character.
  7. "Fake" Cursor: The inactive field also shows you the current cursor position by displaying a dotted frame.
  8. Selected Block: The currently selected data is highlighted by inverting the colors.

Keyboard support

The editor has normal keyboard support (like e.g. Text Editors): Cursor movements, Selection using the "Shift" key, scrolling using "Page Up" and "Page Down" and so on.

Some keys have a special meaning:

  • Tab: You can switch between the Hexadecimal Field and the Character Field using the Tab key (and also Ctrl + T)
  • Shift + Ctrl + 0...Shift + Ctrl + 9: Using these key combinations you can set one of ten Per-File-Bookmarks at the current position. These bookmarks can be defined for each file independently and are persistently stored in the registry.
  • Ctrl + 0...Ctrl + 9: Using one of those ten key combinations you can set the cursor to a previously created Per-File-Bookmark.

Mouse support

Tiny Hexer supports common mouse operations (selection, cursor positioning). Additionally OLE Drag and Drop is supported, so you might drag a selected block of data from an editor to another one, from and to other applications supporting OLE Drag and Drop and even as "Scrap" File to the Desktop.

To open a file in a new editor window, just drag it from an Explorer window to the Toolbar or Status bar of the main window.

You can also use the Scrolling wheel of your mouse to change the number of bytes per row by holding down the Ctrl key during "wheeling".


Customize Toolbar dialog

Using this dialog you can select the command buttons which are shown on the toolbar. This dialog can be accessed by doubleclicking the toolbar or using the "Tools/Customize Toolbar" command.

  1. Available Buttons: This list contains all available commands that can be added to the "Current Buttons" list (and thus to the toolbar). By doubleclicking an item (or using the "Add Button" command (3)), this item is moved from this list to the "Current Buttons" list; it is inserted at the current position. The last entry is the "Separator" item, it is used to separate blocks of command buttons and can be added to the toolbar multiple times
  2. Current Buttons: This list displays all commands that are shown on the toolbar. By doubleclicking an item (or using the "Remove Button" command (4)), an item can be moved from this list to the "Available Buttons" list to remove this command from the toolbar. The uppermost list entry corresponds to the leftmost toolbar button
  3. Add Button: Move the selected command from the left list to the right list to show this command on the toolbar
  4. Remove Button: Move the seleted command from the right list to the left one to remove that command from the toolbar
  5. Move Up: Move the selected command in the right list one position up (and so one button to the left on the toolbar)
  6. Move Down: Move the selected command in the right list one position down (and so one button to the right on the toolbar)
  7. Reset: Reset the "Current Buttons" list's contents to factory defaults
  8. Help: Show this help topic
  9. OK: Accept the changes and rebuild the toolbar command buttons
  10. Cancel: Close the dialog without accepting the changes


Edit Bookmarks dialog

In this dialog you can change and delete Bookmarks. This dialog is displayed by issuing the "Bookmarks/Edit Bookmarks" command.

  1. Bookmark List: This list shows all existing All-Files-Bookmarks. By selecting an item you can modify its properties using the other controls
  2. Move Up: Move the selected bookmark one position up in the "Bookmark List" and also in the bookmarks menu
  3. Move Down: Move the selected bookmark one position down in the "Bookmark List" and also in the Bookmarks menu
  4. Delete Bookmark: Click this button to delete the selected bookmark
  5. Name: Here you can change the name of the selected bookmark which is displayed in the Bookmarks menu
  6. Position: Displays the position that the bookmark represents. You may change it in hexadecimal (prefixed by "0x") or decimal notation
  7. Hex Field: If the box is checked the cursor is set to the Hex field of the editor when selecting the bookmark from the menu. If the box is unchecked, the cursor is set to the Character field
  8. Count: Displays the selection count that the bookmark represents. You may change it in hexadecimal (prefixed by "0x") or decimal notation
  9. OK: Accept the changes and rebuild the Bookmarks menu
  10. Cancel: Close the dialog without accepting the changes
  11. Help: Show this help topic


Set Selection dialog

Use this dialog if you want to choose starting and ending position of a block to be selected numerically . This dialog is opened by the command "Edit/Select".

  1. Selection Start: Type the starting position of the new selection in hexadecimal (prefixed by "0x") or decimal notation. You can also use a position relative to the current cursor position or file end: When prefixing the number by a minus ("-") or plus ("+") sign, the new selection start is relative to the current cursor position, when prefixing by a greater than (">") sign, the new selection start is relative to the file's end
  2. Selection End: Type the end position of the new selection in hexadecimal (prefixed by "0x") or decimal notation. You can also use a position relative to the new selection start or file end: When prefixing the number by a minus ("-") or plus ("+") sign, the new selection end is relative to the selection start typed above, when prefixing by a greater than (">") sign, the new selection end position is relative to the file's end
  3. OK: Use the typed values to select a block in the active editor window
  4. Cancel: Close the dialog without changing the selection
  5. Help: Show this help topic


Convert dialog

Using this dialog you can convert a file or a selected block from one character set to another one. The dialog is displayed by using the "Edit/Convert" command.

  1. From: Select the source character set
  2. To: Select the destination character set
  3. OK: Convert the file or selected block
  4. Cancel: Close the dialog without changing data
  5. Help: Show this help topic


Open Drive/Partition dialog

Using this dialog you can open a hard disk, a floppy disk or a CD Rom sector by sector in an hex editor window. This dialog is opened when issuing the "File/Disk/Open Drive" command. (Windows NT/2000/XP only, you might need administrative privileges to gain direct access to drives)

  1. Drive and Partition List: This list shows the drives and partitions that can be opened in an hex editor window. Hard drives are named "\\.\PHYSICALDRIVE<number>", where number is the system index of the physical drive (drive numbers are zero-based, partition numbers are one-based). CD Roms are called "\\.\CDROM<number>", floppy disks are displayed using the drive letter. CD Roms and floppy disks are not shown if no medium is inserted.
  2. Load Sectors At A Time: This control allows you to display a consecutive sequence of disk sectors at once in the hex editor window.
  3. OK: Open the drive or partition selected in the list above in a new editor window
  4. Cancel: Close the dialog without opening a drive/partition
  5. Help: Show this help topic
  6. Reload: Rebuild the list of available drives/partitions and removeable media
  7. Set As Default: Set the currently selected amount of sectors as default value for this dialog


Read Process Memory dialog

This dialog allows you to select a memory block in another process to be opened in Tiny Hexer. This dialog is opened when executing the "File/Process/Read Process Memory" command. (On Windows NT/2000/XP, you might need administrative privileges to read the memory of other processes)

  1. Reload Process List: The Process list (2) gets updated.
  2. Process List: Displays all available processes currently running. Click on an item to show its memory map in the Memory Blocks list (3).
  3. Memory Blocks List: Displays the memory blocks of the selected process. Memory blocks which are not accessible (PAGE_NOACCESS, MEM_FREE) are hidden from the list.
  4. Preview: Displays the contents of the currently selected memory block. If the data cannot be read, the Preview editor is displayed using a red color.
  5. Unicode: If this box is checked, the contents of the currently selected memory block are treated as 16 bit unicode text (e.g. environment blocks on NT). This settings also affects the search (6) for text data.
  6. Search: Show a Find Dialog to search for data or text in the selected process's memory.
  7. Help: Show this help topic.
  8. Open: Load the selected memory block into an Tiny Hexer editor window.
  9. Cancel: Close this dialog without opening a memory block.


Write Process Memory dialog

This dialog allows you to write back a modified memory block to another process. This dialog is shown when executing the "File/Process/Write Process Memory" command. (On Windows NT/2000/XP, you might need administrative privileges to write to the memory of other processes. Depending on the properties of the selected memory block, writing might not be possible at all.)

  1. Process: Shows the process that owns the edited memory block.
  2. Base Adress: Displays the base address of the modified memory block. This address can be changed to write to a different address.
  3. Selected Bytes Only: Allows you to write only the data currently selected in the editor.
  4. OK: Write the memory block.
  5. Cancel: Close this dialog without writing the memory block.
  6. Help: Show this help topic.


Find/Replace window

In this window you can type hex values or text you want to search for in the active document. If the data has been found, you can replace the current or all occurrences with other data. The window is displayed by the "Edit/Find/Replace" command.

Finding data:

  1. Data Edit: Here you can type the hexadecimal byte values or text you want to search for
  2. Find Text: If the box is checked, the text in the Data Edit is treated as literal text. if the box is unchecked, it is treated as hexadecimal byte values. In text mode the current Character translation is used, e.g. searching for "Text" in EBCDIC mode will search for the EBCDIC representation of the Ansi text "Text"; searching for "Text" in Unicode mode searches for the Unicode representation of the Ansi text "Text" and so on
  3. Ignore Case: If the box is checked, the search is case insensitive, so uppercase and lowercase representations of the values in the Data Edit will be found
  4. Use Wildcard: If this box is checked, the value in the Wildcard Edit is used as "any byte" value (works like the dos file wildcard "?")
  5. Wildcard Edit: Here you can type a value in either hexadecimal byte form (2 hex digits, e.g. FF to use the character with the ascii value 255) or as a character (prefixed by a single quote, e.g. '? to use the question mark).
    This value is used as a wildcard while searching. In the first example the values "00 02 00 00", "00 02 01 00" ... "00 02 FF 00" would be found
  6. Regular Expression: If the box is checked, Tiny Hexer performs a pattern search based on regular expressions in the data (like the un*x grep utility). In this case, the pattern cannot be typed in hex ("00 02 FF 00") notation; also the Wildcard Edit is disabled as regular expression based searches are much more flexible than using just a single wildcard
  7. Find: Start/continue searching
  8. Close: Close this window
  9. Help: Show this help topic
  10. Replace: This button is enabled when the data has been found. By clicking this button the Replace controls are made available.

Replacing data:

  1. Replace Data Edit: Here you can type the hexadecimal byte values or text you want to use as replacement data. Leave the field empty to remove the data searched for from the active document
  2. Is Text: If the box is checked, the text in the Replace Data Edit is treated as literal text. if the box is unchecked, it is treated as hexadecimal byte values. In text mode the current Character translation is used, e.g. replacing with "Text" in EBCDIC mode will use the EBCDIC representation of the Ansi text "Text"; replacing by "Text" in Unicode mode replaces with the Unicode representation of the Ansi text "Text" and so on
  3. Replace: Replace the current occurrence of the values in Find Data Edit with the values from Replace Data Edit
  4. Replace All: Replace all occurrences of the values in Find Data Edit with the values from Replace Data Edit


Print Preview window

This windows show a print preview of the active editor document. You can also start the actual printing here. The window is shown by using the "File/Print" command.

  1. Page Selector: Select the page you want to show in the Preview Pane
  2. Print: Select the data range to print:

    • All Pages: Print the whole document
    • Current Page: Print the page selected in the Page Selector
    • Selection: Print the current editor selection only
    • Editor View: Print the data range actually visible in the editor

  3. Margins: Enter the top, left, right and bottom print margin in Millimeters
  4. Font: Click this button to choose the font used for printing
  5. Print colors: Check this box to use the editor's colors for printing
  6. Use Background Color: Check this box to paint the paper's background using the editor's background color
  7. Selection printed bold: Check this box to print the block currently selected in the editor using a bold font
  8. Page Header: The contents of this field are printed at the top of each page. The page header consists of three parts (left, centered and right) which are separated by pipe characters ("|") in this edit box. There are a few macros available here:

    • %f: Print the filename of the printed document (without path)
    • %F: Print the filename of the printed document (including path)
    • %p: Print the currently printed page's number
    • %P: Print the number of pages
    • %t: Print the current time
    • %d: Print the current date
    • %>: Print the long name of the active document's character translation (like "Windows", "Dos 8 Bit", "Unicode Big Endian"...)
    • %<: Print the short name of the active document's character translation (like "WIN", "DOS", "UCBE"...)

  9. Page Footer: The contents of this field are printed at the bottom of each page. The Page Header macros are available too. The footer also consists of a left, a centered and a right part
  10. Preview Pane: This part displays a preview of the selected page
  11. Zoom Button: Use this button to change the preview's size
  12. Help Button: Show this help topic
  13. Print Setup Button: Displays Windows' Printer Setup dialog
  14. Print Button: Start printing and close this window
  15. Close Button: Close this window without printing


Structure viewer

This viewer is used to display the contents of a file in a structured manner to make it easier to understand the data. The window is shown by checking the "Tools/Structure Viewer" command.

The viewer uses scripts written in Tiny Hexer Script to display the data structures. Sample scripts for .zip, .exe and .bmp files are provided. You can write your own scripts for different data formats. After storing them in the <application directory>\scripts\Structure Viewer directory they can be used with the Structure viewer by clicking the Open Structure Script button and loading the script.

Scripts to be executed within the Structure Viewer must contain the directive line OPTION TARGET, STRUCTUREVIEWER.

  1. Clear: Unload the currently loaded script and clear the Structure Browser
  2. Open Structure Script: Load a structure script into the viewer and try to display the data structures of the current hex editor window's file
  3. Update: Rescan the active editor window's file data and display its structures in the browser
  4. Stop: Scanning data might take some time. While structure scanning is executing, you can stop this process by clicking this button
  5. Save browser contents: Save the Structure Browser contents either in text or HTML format
  6. Print browser contents: Print the Structure Browser contents after displaying a printing options dialog
  7. Help: Show this help topic
  8. Structure Browser: This browser actually displays the data structures
  9. Links: Underlined text marks links. Those links are useful to locate specific positions and select a specific block in the editor window. Links are created by the scripts (by using tagged variables)


Value editor

Using the Value Editor you can edit hex data in different formats (like Byte, Char, DWORD, IEEE Float...). The window is shown by checking the "Tools/Value Editor" command.

The Value Editor displays the data at the cursor position in the active editor window in the selected data format. The data range currently being displayed and edited in the value editor is highlighted using a different color in the hex editor.

  1. Data Type Selector: Here you can choose the data type to display/edit
  2. Big Endian: By checking this box you tell the value editor to read/store the data in big endian format (this data format is used e.g. on some Motorola processors). If the box is unchecked, low endian format is used (e.g. Intel)
  3. Value: The actual data in the specified format. You can change the value by overwriting the value. If the "char" data type is used, you can either set the value in numerical notation or as a character. this character value must be put in quotes (e.g. "A")
  4. Radix: If an integer data format is chosen, you can change this value to display/edit the value in octal (8), decimal (10) or hexadecimal (16) notation
  5. Bits: This panel shows the value as single bits, bytes are separated by a vertical line. You can change a single bit by clicking the corresponding box. a filled box means "1", an empty box means "0". By right clicking the Bits panel, a popup menu is shown that allows you to switch or clear the current or all bytes of the value
  6. One Value Left: The cursor in the editor window is set to current position - sizeof(selected data type), so if the selected data type is Word, the cursor is set two bytes to the left because a 16 bits word consists of two bytes. After moving the cursor, the new data block is displayed in the value editor
  7. One Byte Left: The cursor is set to current position - 1
  8. One Byte Right: The cursor is set to current position + 1
  9. One Value Right: The cursor is set to current position + sizeof(selected data type)
  10. Find Data: On clicking this button, the hexadecimal representation of the current Value is displayed in the Find/Replace dialog to simplify searching for e.g. specific floating point values
  11. Help: Show this help topic
  12. Apply Changes: After you made manual changes to the data (by modifying the data in the Value edit box or changing some bit in the Bits panel), you can write back the changed data to the editor by clicking this button


Position list

This list is used to store different file positions to quickly navigate in a document. The window is shown when checking the "Tools/Position List" command.

In this list window you can collect different file positions and selections. The Edit/Store in Position List and Edit/Find All and Store commands are used to add entries to this list.
You can save position lists to files, print them and export them to text files. Each list can have a description that is stored and printed.
The list has a context menu with additional commands.

  1. Load from file: Load a previously saved list from disk
  2. Save to file: Save the contents of the list to either a list file that can be reloaded or a text file
  3. Print list: Print the current list
  4. Description: In this field you can change the current list's description
  5. The List: Each entry in this list stores a cursor position/selection. The display format depends on the Number Format setting. When doublecklicking an entry or pressing the RETURN key, the cursor in the active document is set to this position. The number in parenthesis shows the amount of data to be selected
  6. Delete: This context menu entry allows you to remove the selected entries from the list
  7. Shift: You will be asked to enter an offset value (+/-), then all selected entries' position will be shifted by this value
  8. Copy: Copy the current selection to the clipboard
  9. Select All: Select all entries in the list
  10. Entry Count: This value tells you the number of entries in the list


File Import

This dialog allows you to select the data format of a file you want to import. The dialog is opened by using the "File/Import" command.

Files in specific formats can be imported by executing one of the Tiny Hexer Scripts in the <application directory>\scripts\import directory. You can place your own import scripts here to add import capabilities for different file formats to Tiny Hexer. These scripts need to be formatted specially1 to be recognized by this dialog.

  1. Select Format: Choose one of the data formats available for import
  2. Import: Start data import
  3. Cancel: Close the dialog without importing the selected file
  4. Help: Show this help topic

1) Import script file format:
The first two lines in an import script have a special meaning. They must start with an equal sign "=". The text immediately following the equal sign is read by the Import Dialog to determine the description of the import script (first script line) and the default file extensions of data files that should be imported using this script (second line). When the Import Dialog is shown it checks whether the file extension of the file to be imported "belongs" to one of the import scripts. If yes, this script is automatically selected in the "Select Format" list.

Additionally import scripts must contain the directive line OPTION TARGET, IMPORT.


File Export

This dialog allows you to select the data format of a file you want to export. The dialog is opened by using the "File/Export" command.

Open files can be exported to different data formats by executing one of the Tiny Hexer Scripts in the <application directory>\scripts\export directory. You can place your own export scripts here to add export capabilities for different file formats to Tiny Hexer. These scripts need to be formatted specially1 to be recognized by this dialog.

  1. Select Format: Choose one of the data formats available for export
  2. Export to clipboard: If this box is checked, the file is exported to the clipboard rather than the disk
  3. Selection only: Export the currently selected block only
  4. Export: Start file export
  5. Cancel: Close the dialog without exporting data to a file or the clipboard
  6. Help: Show this help topic

1) Export script file format:
The first three lines in an export script have a special meaning. They must start with an equal sign "=". The text immediately following the equal sign is read by the Export Dialog to determine the description of the export script (first script line), the filter used in the save dialog (second line) and the default file extension of files being exported using the script (third line).

Additionally export scripts must contain the directive line OPTION TARGET, EXPORT.


Edit Tools dialog

This dialog allows you to modify the list of external tools on the Tools menu. It can be accessed by using the "Tools/Configure Tools" command.

  1. Tools list: All external tools currently displayed on the Tools menu can be modified by doublecklicking the corresponding entry on this list
  2. Move Up: The selected tool entry is moved up one row in the list (and thus on the Tools menu)
  3. Move Down: The selected tool entry is moved down one row in the list (and thus on the Tools menu)
  4. New: Add a new entry to the tools list and modify its properties
  5. Delete: Remove the selected entry from the list (and the Tools menu)
  6. Help: Show this help topic
  7. OK: Accept the changes and rebuild the Tools menu
  8. Cancel: Close the dialog without accepting the changes


Tool properties

This dialog allows you to modify the properties of each external tool on the Tools menu. It is used by the Edit Tools dialog.

  1. Caption: A description of the tool as it is displayed on the Tools menu
  2. Program: The filename of the program. The program can either be an executable file or a Tiny Hexer Script
  3. Select Program: A file selection dialog is shown so you can choose the program/script
  4. Directory: The working directory used when executing the program
  5. Arguments: Command line arguments that will be passed to the program/script. A Tiny Hexer script can access these arguments using PARAM_COUNT and PARAMS().

    Some macros can be used to control tool execution:

    $(INPUT): You will be prompted to type an argument. This text will replace the macro on tool execution

    $(SAVE): Save the active document before executing the tool. The macro is removed from the parameters passed to the tool

    $(SCRIPT): This macro is removed from the list of arguments. It tells Tiny Hexer that the tool is a Tiny Hexer Script rather than an executable program

    $(FILE): This macro is replaced by the filename of the active document on tool execution

    $(POSITION): This macro is replaced by the position of the cursor in the active document on tool execution

    $(SELSTART): This macro is replaced by the start of the selected block in the active document on tool execution

    $(SELCOUNT): This macro is replaced by the amount of selected data in the active document on tool execution

  6. OK: Accept the changes and close this dialog
  7. Cancel: Close the dialog without accepting the changes
  8. Help: Show this help topic


File statistics window

This window shows you some statistics for the current file or selection. It can be displayed using the "File/Statistics" command.

  1. Byte Usage: This list shows you the occurence of each byte value in the data. Click on a list column to change the sort order.
  2. Arithmetic Mean: Displays the arithmetic mean of all data values, depending on the selected data type (5).
  3. Geometric Mean: Displays the geometric mean of all data values, depending on the selected data type (5).
  4. Standard Deviation: Displays the standard deviation of all data values, depending on the selected data type (5).
  5. Data Type: Choose the type of the data to calculate the statistics and display the graph.
  6. Scale to range of used values: Scale the graph axes to display just the range of actual data values in the current file.
  7. Graph: Graphical representation of the data.
  8. Close: Close this window.
  9. Export: After selecting a filename, the current statistics are saved in RTF format.
  10. Help: Show this help topic.


Global Options dialog

This dialog allows you to modify the global settings of Tiny Hexer. It can be accessed from the "Options/Global Settings" menu.
  • General 1
  • General 2
  • Scripts
  • Keyboard Mapping

General Settings (page 1)

  • Support OLE Drag 'n' Drop: If this box is checked, you can use drag and drop to copy or move data from Tiny Hexer to other applications and vice versa. You can also drag data from an editor to a folder in Explorer to create so called "Scrap Files"
  • Maximize new editor windows: If this box is checked, Tiny Hexer creates new editor windows in maximized state
  • Initial Insert mode on file opening: If this box is checked (default), documents are opened in Insert mode (i.e. data is inserted when typing values). If the box is not checked, documents are opened in Overwrite mode (on typing values the current data is overwritten). New (empty) editor windows are always created in Insert mode
  • Show Hex chars in lower case: If this box is checked, hexadecimal numbers are displayed using lower case letters in the editor's hexadecimal field, otherwise upper case letters are used
  • Use Mouse wheel for zooming: If this box is checked, you can change the number of bytes displayed in each row using the mouse wheel and pressing the CTRL key
  • White space replacement: The character that is displayed in the editor's character field when displaying data in the value range 0..31
  • Maximum size of Undo buffer: Tells Tiny Hexer how much memory it should provide for undo storage. The higher this value, the more modification steps are undoable. If this limit gets exceeded, the oldest undo record is removed from memory, so the corresponding modification can no longer be undone

General Settings (page 2)

Backups

  • Create backups: If this box is checked, Tiny Hexer creates backups of modified files before they are re-written to disk
  • Backup file extension: Tells Tiny Hexer what file extension it should add to file being backuped

Clipboard

  • Text is in Hex Text format: If this box is checked, text data pasted from clipboard will not be inserted as is, but read as Hex Text ("00 01 02 03...")
  • Preserve contents on exit: If this box is checked and Tiny Hexer has put some data to the clipboard, the clipboard data will be available after Tiny Hexer terminated. Otherwise, Tiny Hexer clipboard data is removed on exit

Shortcuts

Here you can define the keyboard shortcuts of Tiny Hexer's menu commands. Select a command from the commands list, focus the hotkey box and press the key combination you want to use to execute the command.

Scripts

  • Startup Script: Here you can choose a Tiny Hexer Script which automatically gets executed when Tiny Hexer is started.
  • Termination Script: Here you can choose a Tiny Hexer Script which automatically gets executed when Tiny Hexer is terminated.

You might try the startup.mps/stop.mps script couple located in the scripts/start-stop directory. These scripts can re-open the files which were opened in the previous Tiny Hexer session. Even the selections are remembered.

Keyboard Mapping

In Tiny Hexer it is possible to reconfigure the keyboard when typing hexadecimal values into an editor's hexadecimal field and characters into its character field independently. E.g. in some keyboard layouts typing numbers needs the usage of additional control keys, so keyboard reconfiguration could be used to map the key "q" to the number "0" to simplify number typing in the hexadecimal field (where the "q" character is not used).

  1. Mappings list: Select a key mapping to change its properties
  2. Add: Add a new key mapping
  3. Delete: Remove the selected key mapping
  4. Clear: Clear the whole list
  5. Character typed: The source key that you want to remap to a different one
  6. Maps to: The target key press sent to the editor instead of the source key


Editor Options dialog

This dialog allows you to modify editor related settings of Tiny Hexer. It can be accessed from the "Options/Editor Settings" menu.
  • Row size: Select how many bytes are displayed in each editor's row
  • Column size: Select how many bytes are displayed per column
  • Block size: Select how many bytes are displayed per block
  • Show gridlines: If this box is checked, lines are drawn between rows and columns in the editor
  • Gutter has 3D borders: Display a 3D border frame around the editor's internal borders
  • Fixed file size: If this box is checked, you cannot change the size of the file being edited. This option cannot be changed when editing disk sectors or memory blocks
  • Show ruler bar: Display a ruler bar on top of the editor
  • Swap half bytes: If this box is checked, nybble order is reverted in the editor's hexadecimal field (so e.g. the byte "01" will be displayed as "10")
  • Font: Change the font used in the editor
  • Colors: Select an item from the list and change its Text and Background color

Default checkbox: Mark this check box to apply the settings to all future editor windows. If this box is unchecked, the settings apply to the active editor window only.

Apply to all checkbox: Mark this check box to apply the settings to all currently opened editor windows.


Edit Custom Character Translation

In this dialog you can create and modify the custom character translation tables (e.g. to work with files in special EBCDIC formats). This dialog can be accessed by using the "Options/Custom Character Translation Table" command.

Each custom character table consists of two parts: Conversion from Windows to custom charset and from custom to Windows charset. The first one is used to convert characters typed in the character field of an editor window, the second one is used to convert characters from the file data to the windows charset when displaying them in the editor's character field.

  1. Load Table: Load a character translation table from disk
  2. Save Table: Save the modified table to a file on disk
  3. Generate Second Table: If the modified table ("from Windows" or "to Windows") is reversible, the second table ("to Windows" resp. "from Windows") can be automatically generated using this button. Reversible here means that each source character maps to exactly one target character
  4. Reset: Reset the table to 1:1 character mapping
  5. Copy From: Load one of the predefined tables (Macintosh, EBCDIC CP38 or OEM (DOS)) to use it as starting point to create your own table
  6. Table Editor: Using the editor you can modify the character mappings. E. g. if source character 0x5B should map to target character 0x4A in your customized character translation table, set the cursor to position 0x5B and type the value 4A in the editor's hexadecimal field
  7. Current Character Mapping: Displays the hexadecimal code of the source and the target character, separated by a colon
  8. From Windows Codepage: Click this tabulator to edit the table being used to map Windows characters to custom charset characters
  9. To Windows Codepage: Click this tabulator to edit the table being used to map custom charset characters to Windows characters
  10. Help: Show this help topic
  11. OK: Store the modified character translation table and close the dialog. After this you can use the newly created table by switching to "Custom Translation" in the "View/Character Translation" menu
  12. Cancel: Close the dialog without storing the table


Command line parameters

Here the command line parameters supported by Tiny Hexer are listed.

The following command line parameters are supported:

  1. filename: File filename is opened in Tiny Hexer.
  2. /n: Normally, Tiny Hexer opens an untitled editor window if no files to open are given on the command line. If this parameter is present, no such untitled editor window will be opened.
  3. /p filename: File filename is opened and printed. If no additional arguments are given, Tiny Hexer terminates after printing.
  4. /s filename: The Tiny Hexer Script file filename is opened and executed.


Tiny Hexer Script

In this topic you will find an introduction to the Tiny Hexer Script language.
  • Overview
  • Data Types
  • Variables
  • Expressions
  • Operators
  • Directives
  • Commands
  • Functions

Overview

Tiny Hexer Script is an interpreted programming language to add scripting capabilities to Tiny Hexer. Scripts are stored in text files having the file extension .mps. Each script consists of a sequence of commands separated by line feeds and/or colons (":"). Commands and functions are case insensitive. Comments ca be stored in a script file using the equal sign ("="). The language has conditional (IF...[ELSE...]ENDIF, REPEAT...UNTIL, WHILE...ENDWHILE) and unconditional flow control commands (CALL, GOTO and LOOP). Data can be stored in variables of various data types (TEXT, CHAR, BYTE, WORD, DWORD, QWORD, FILE and VARREF).

A simple Tiny Hexer Script might look like the following (without line numbers):

1)    = Sample Script
2)    VAR txt TEXT
3)    @@LOOP_1
4)    LET txt = INPUT("Input Query", "Please enter some text (no text to exit)", txt)
5)    IF txt == "":END:ENDIF
6)    MSGBOX ("You entered:\r\n"+txt), 0x40
7)    GOTO LOOP_1

Description

Line 1): The equal sign ("=") tells Tiny Hexer to ignore the rest of this line (used to store comments in the script file).

Line 2): The variable txt of data type TEXT is defined (all variables must be defined in Tiny Hexer Script before using them).

Line 3): The label LOOP_1 is defined. Labels are used to name subroutines (CALL and LOOP commands) and targets for the GOTO command.

Line 4): The result of the function INPUT(...) is assigned to the variable txt.

Line 5): This line consists of three commands, separated by colons. The first command (IF) checks if the condition (txt == "") is met. If yes, the following command is executed. If not, the script continues at the command after the ENDIF command. The second command (END) tells Tiny Hexer to stop execution of the script. The third command (ENDIF) terminates the IF block.

Line 6): The MSGBOX command is executed to show a message to the user (the text he entered in this case).

Line 7): The GOTO command tells Tiny Hexer to continue script execution at label LOOP_1.


Tiny Hexer Script: Data Types

Tiny Hexer Script uses different data types. They are explained here.
  • Overview
  • Literals
  • TEXT type
  • CHAR type
  • BYTE type
  • WORD type
  • DWORD type
  • QWORD type
  • FILE type
  • VARREF type

Overview

Variables, commands, functions and expressions in Tiny Hexer Script use resp. have different data types. Using the wrong data type will lead to "Type mismatch" errors during script compilation or execution.

Textual data types:

The TEXT and CHAR data types are used to store textual data. TEXT data can hold whole text strings, the CHAR type can hold only one character (1 Byte).

Numeric data types:

The BYTE (1 Byte, unsigned), WORD (2 Byte, unsigned), DWORD (4 Byte, unsigned) and QWORD (8 Byte, signed) data types are used to store integral numeric values.

Other data types:

See FILE and VARREF later in this section.

Type compatibility and conversion:

All numeric data types are compatible, though assigning a value greater than the target type's range will lead to incorrect results (e.g. assigning the value 258 to a BYTE type variable will lead to a range overflow, so actually the value 2 is stored in that variable: 0x0102 -> 0x02).
The CHAR data type is also compatible to numeric data types, the byte value of the character stored is used if a CHAR is used as a numeric data.

TEXT and CHAR textual data types are compatible, so a CHAR data can be used where a TEXT data is expected. If a TEXT data is used where a CHAR is expected, the first character of the TEXT data is used. If the data contains an empty text, an error is raised.

To convert textual data to numeric data, use the BYTE(), WORD(), DWORD() and QWORD() functions. Those functions raise an error if the data string cannot be converted to a number (e.g. '0x200', '-345', '755o' are convertible text strings, 'notanumber' isn't).

To convert numeric data to text, use the CHAR() and TEXT() functions. The format of the resulting text string when using the TEXT() functions depends on the values of NUMBER_PREFIX, NUMBER_SUFFIX and NUMBER_RADIX.

The FILE type is compatible with itself only.

The VARREF type is compatible with itself only, but you can use the DEREF() function to retrieve the value of the referenced variable. Use the @ operator to assign a variable to a VARREF data.

Literals

Tiny Hexer supports textual and numeric literals in different formats.

Textual literals can be written down in a script in two different formats:

  • Single quoted text literals (textual data enclosed by single quotes (apostrophes)):
    Each character between the enclosing single quotes is read as is (e.g. 'the char combination \n has no special meaning in single quoted text literals')
  • Double quoted text literals (textual data enclosed by double quotes (")):
    The backslash "\" is used as meta/escape character, so is it possible to write down "untypeable" characters in the script. the following meta combinations are recognized:

    • \t: character with the ascii value 9 (tabulator)
    • \n: character with the ascii value 10 (line feed)
    • \r: character with the ascii value 13 (carriage return)
    • \\: single backslash
    • \0X<2 digit hex number>: character with the ascii value of <2 digit hex number>
    (e.g. "the char combination \n stands for a line feed in double quoted text literals")

Numeric literals (Numerals) can be written down in a script in four different formats:

  • Decimal numeric literals:
    Decimal numeric literals consist of sequences of numeric characters (0,1,2,3,4,5,6,7,8,9) and may be prefixed by a minus sign "-" to indicate a negative number (e.g. -912340)
  • Hexadecimal numeric literals:
    Hexadecimal numerals are prefixed by "0x" and consist of sequences of hexadecimal digits (0..9, A..F) (e.g. 0xAFD245FE)
  • Binary numeric literals:
    Binary numeric literals are prefixed by the percent sign "%" and consist of sequences of binary digits (0,1) (e.g. %011010100010110)
  • Octal numeric literals:
    Octal numeric literals consist of sequences of octal digits (0,1,2,3,4,5,6,7) and are immediately suffixed by the letter o (e.g. 0755o)

TEXT data type

TEXT data is used to store textual data (using the DATA2TEXT() and TEXT2DATA() functions TEXT data can store any data and even some kind of array fields). TEXT data can store from 0 up to (2**31 - 1) data characters (depending on available memory), the amount of data stored in a TEXT data can be retrieved using the TEXTLEN() function.

TEXT literals can be written using textual literals.

CHAR data type

CHAR data is used to store single data characters (1 Byte).

CHAR literals can be written using either one-char textual or numeric literals.

BYTE data type

BYTE data is used to store 8 Bit (= 1 Byte) unsigned numeric values.

BYTE literals can be written using numeric literals.

WORD data type

WORD data is used to store 16 Bit (= 2 Byte) unsigned numeric values.

WORD literals can be written using numeric literals.

DWORD data type

DWORD data is used to store 32 Bit (= 4 Byte) unsigned numeric values.

DWORD literals can be written using numeric literals.

QWORD data type

QWORD data is used to store 64 Bit (= 8 Byte) signed numeric values. The most significant bit is used as sign indicator, so only 63 Bits are available for data.

QWORD literals can be written using numeric literals.

FILE data type

FILE data contain private structures used to access file handles in file related commands and functions.

VARREF data type

VARREF data structures contain references to variables and are used e.g. by the FILEREAD() function.


Tiny Hexer Script: Variables

In Tiny Hexer script you can use variables to store specific data.
  • Overview
  • Variable Tagging
  • Special Variables

Overview

Valid variable names are sequences of at least one alphanumeric character or the underline character (_). A variable name must not start with a number digit. Valid variable names are e.g. _1, Var1, _test_. Invalid variable names are e.g. 1var, v$a. Identifiers reserved in Tiny Hexer Script (like function and command names) cannot be used as variable names.

Variables must be declared before accessing them in a script using the VAR command. When a variable is declared using the VAR command, its data type is defined and cannot be changed afterwards.

To assign data to a variable, use the LET command.

By default, sub routines (CALL and LOOP commands) use copies of declared variables (like environmental variables in batch scripts), so the sub routine can access the variable and change its value locally, but after termination of the sub routine (RETURN command) the original value of the variable is restored. This behaviour can be changed using the OPTION GLOBALVARS directive.

Variable Tagging

Variable tagging is used to show links in the Structure Viewer. Each variable can have a position and length tag. Variable tagging is disabled by default, this behaviour can be controlled by the OPTION READTAGS directive.

If tagging is enabled, the FILEREAD command and function set the tag of the variable to the file position before reading and the amount of data being read. The following commands and functions allow you to access and modify variable tags: COPYTAGS, TAGVAR, TAG_POS() and TAG_LEN().

Special Variables

The following special variables exist in Tiny Hexer:

  • COMPARE_COUNT (DWORD, readonly)

    Reading this variable returns the number of difference blocks after a file comparison has been made.
    See also COMPARE_START() and COMPARE_END().

  • CURRENTFILE (TEXT, read/write):

    Reading this variable returns the filename of the active editor window. If no editor window is open, the variable contains an empty text. On setting this variable, Tiny Hexer tries to find an editor window whose filename matches the value and brings it to front. If no matching editor window is found, an error occurs.

  • ERRORLINE (DWORD, readonly):

    Reading this variable returns the number of the script line where the last error occurred.
    See also ERRORHANDLER, ERRORMESSAGE, ERRORNUMBER.

  • ERRORMESSAGE (TEXT, readonly):

    Reading this variable returns the textual representation of the last script error.
    See also ERRORHANDLER, ERRORLINE, ERRORNUMBER.

  • ERRORNUMBER (DWORD, readonly):

    Reading this variable returns the numerical value of the last script error. Some predefined errors exist, they are explained in the file scripts\inc\def.mps
    See also ERRORHANDLER, ERRORLINE, ERRORMESSAGE.

  • FILE_COUNT (DWORD, readonly):

    Reading this variable returns the number of open editor files in Tiny Hexer.
    See also FILES().

  • LOOP (DWORD, readonly)

    On subroutine execution via the LOOP command, this variable contains the current loop index.

  • NUMBER_PREFIX (TEXT, read/write)

    Tells Tiny Hexer how it should convert numeric values to text using the TEXT() function (e.g. '0x': 48 -> '0x30', '$': 32 -> '$20').

  • NUMBER_RADIX (BYTE, read/write)

    Tells Tiny Hexer how it should convert numeric values to text using the TEXT() function (e.g. if set to 10, numbers are converted to decimal text, if set to 16, numbers are converted to hexadecimals and so on).

  • NUMBER_SUFFIX (TEXT, read/write)

    Tells Tiny Hexer how it should convert numeric values to text using the TEXT() function (e.g. 'h': 80 -> '50h').

  • PARAM_COUNT (DWORD, readonly)

    Stores the number of arguments passed to the script when it's started by a Tools Menu item.
    See also PARAMS().

  • POSITION_COUNT (DWORD, readonly)

    Reading this variable returns the number of entries in the Position list.
    See also POSITIONS(), POSITION_ADD, POSITION_SELECTED(), POSITION_DESC.

  • POSITION_DESC (TEXT)

    Sets or retrieves the text of the description in the Position list.
    See also POSITIONS(), POSITION_ADD, POSITION_SELECTED(), POSITION_COUNT.

  • SCRIPTFILENAME (TEXT, readonly)

    Contains the file name of the script itself.

  • SCRIPTLINE (DWORD, readonly)

    Contains the current script line number.

  • SCRIPTPOS (DWORD, readonly)

    Contains the binary script position.


Tiny Hexer Script: Directives

Directives are used to control the compilation of Tiny Hexer Scripts.

Directives tell Tiny Hexer how to compile Tiny Hexer Scripts. Only the compilation of commands following a directive is affected by that directive. Directives are written in the form

OPTION <name of the directive> <value>

Currently the following directives are supported:
OPTION GLOBALVARS, <0 or 1>

If GLOBALVARS is set to 1, only one set of variables exist, so subroutines (called by the CALL and LOOP commands) can change variables globally.

When set to 0 (default), subroutines get their own copy of all variables, so they can change them locally, but on termination of the subroutine (RETURN command), changes are lost and the variable contents are reset to the values before calling the subroutine.

See also variables.
OPTION READTAGS, <0 or 1>

If READTAGS is set to 1, the FILEREAD command and function store the current file position and amount of data read.

See also Variable Tagging.
OPTION TARGET, <IMPORT, EXPORT or STRUCTUREVIEWER>

Using the TARGET directive you can tell Tiny Hexer that a script is not an ordinary one, but should be used with the File/Import command, the File/Export command or the Structure Viewer. If such a script is opened using the Tools/Execute Script command, a warning message is displayed telling the user that the script is not designed to be executed directly. Also the Structure Viewer and the Import/Export commands refuse to use scripts not designed for them.


Tiny Hexer Script: Commands

This page shows all available Tiny Hexer Script commands.
! @ C D E F G I L M O P R S T V W
CALL target [, param1, param2...]
Parameters:

target: the name of a label in the current script
param1/2...: optional expressions that are pushed to the stack

more...

less...

CALL continues script execution at the position marked with the label target after storing the current command position internally. The RETURN command is used to finish a subroutine and continue script execution at the command following the CALL command.

The CALL command can have optional parameters that are pushed to the stack. The subroutine can retrieve those parameters using the POP command. (Note: Because the stack is a LIFO, the first POP in a subroutine returns the last parameter, the second POP returns the last but one parameter...).
See also: LABEL, RETURN, LOOP, GOTO, PUSH, POP, OPTION GLOBALVARS directive.
Sample:
VAR t1 TEXT,  t2 TEXT

= pushes 'first', than 'second' to the stack and calls the label concat
CALL concat, "first", "second"

= use the END command to avoid running into the subroutine again
END

LABEL concat
POP t1
= t1 now contains 'second' (the last parameter pushed to the stack)

POP t2
= t2 now contains 'first' (the last-but-one parameter pushed to the stack)

= displays the message 'second first' !!!
MSGBOX t1+" "+t2

= return from the subroutine to the command following the CALL
RETURN
CONCAT textvar, textexpr
Parameters:

textvar: the name of a text variable
textexpr: an expression of type text

more...

less...

CONCAT concats the value of the text-type expression textexpr to the text already stored in the text-type variable textvar. (Note: The CONCAT command is faster than the text-type '+' operator.)
See also: text-type '+' operator, INC.
Sample:
VAR txt TEXT

= variable txt is set to the text 'foo'.
LET txt = "foo"

CONCAT txt, "bar"
= variable txt now contains the text 'foobar'.
COPYTAGS targetvar, sourcevar
Parameters:

targetvar and sourcevar: variable names

more...

less...

The COPYTAGS command is used to assign the tag of variable sourcevar to variable targetvar.
See also: Variable Tagging, TAGVAR, TAG_POS() function, TAG_LEN() function, OPTION READTAGS directive.
Sample:
VAR foo TEXT, bar TEXT, tagstorage TEXT

= sets the tag_pos field of the variable foo to 2000 and the tag_len field to 4
TAGVAR foo, 2000, 4

= copies the tag of the variable foo to the variable bar
COPYTAGS bar, foo

= enable decimal number to text conversion
NUMBER_PREFIX=''
NUMBER_SUFFIX=''
NUMBER_RADIX=10

= assigns the tag_pos field of bar to the variable tagstorage
LET tagstorage = TEXT(TAG_POS(@bar))

= displays the tag_pos field of variable bar
MSGBOX ("The Tag position of bar is: "+tagstorage)
DEF name value
Parameters:

name: a valid identifier name
value: an expression

more...

less...

The DEF pseudo command is used to give certain expressions or values descriptive names (similar to #define in the C programming language). After assigning a descriptive name to a value, this name stands for the value in the script.
Sample:
= tell Tiny Hexer Script to substitute all literal occurances of FOOBAR with 'Foo/Bar'
= and all literal occurances of MYMESSAGE with FOOBAR+'/whatsoever'
DEF FOOBAR 'Foo/Bar'
DEF MYMESSAGE FOOBAR + '/Whatsoever'

= show if it works
MSGBOX MYMESSAGE
END

more...

less...

The END command is used to stop script execution.
Sample:
VAR foo TEXT

END
= script execution is terminated at this position

LET foo = "bar"
= this command is never executed
ERROR textexpr
Parameters:

textexpr: an expression of type text

more...

less...

The ERROR command displays an error message textexpr and terminates script execution.
Sample:
VAR dividend DWORD divisor DWORD quotient DWORD

= enter divisor and dividend
LET dividend = DWORD(INPUT('Enter dividend:'))
LET divisor = DWORD(INPUT('Enter divisor:'))

IF ((divisor == 0) OR (dividend == 0))
  = throw an errror message and terminate the script
  ERROR "Neither dividend nor divisor must be zero!"
ELSE
  LET quotient = dividend / divisor:= calculate quotient

  = enable decimal number to text conversion
  NUMBER_PREFIX=''
  NUMBER_SUFFIX=''
  NUMBER_RADIX=10

  MSGBOX ("Result: "+TEXT(quotient))
ENDIF
ERRORHANDLER target | NONE
Parameters:

target: name of a label in the current script (or the special value NONE to disable error handling)

more...

less...

The ERRORHANDLER command allows to continue script execution at the label target if an error occurs. If the argument NONE is passed to the command, error handling is disabled, so the script will be terminated on error (default).

(Note: if an error occurs at script execution and the label target is called, error handling is automatically disabled to avoid possible infinite recursions caused by errors in the handler itself)
See also: ERRORLINE, ERRORMESSAGE and ERRORNUMBER special variables.
Sample:
INCLUDE 'def.mps'

VAR a DWORD, b DWORD

ERRORHANDLER errorlabel

= if an invalid numerical value is entered, the script is continued at
= the @errorlabel position
@@inputa:a= DWORD(INPUT('enter number 1'))
@@inputb:b= DWORD(INPUT('enter number 2'))

MSGBOX TEXT(a+b)

= force an error message
a = "this does not work, since a is a numerical variable!"

END

@@errorlabel

= exit if cancel command has been invoked
IF (ERRORNUMBER == ERROR_ABORT):END:ENDIF

ERRORHANDLER errorlabel:= reenable error handler

= if error occured in line  9 (@@inputa...), goto @@inputa,
= if error occured in line 10 (@@inputb...), goto @@inputb
IFGOTO ERRORLINE, 9, inputa, 10, inputb

= show error message and exit otherwise
ERRORHANDLER NONE
ERROR ERRORMESSAGE
EXTERN 'cmdname' [, param1, param2...]
!cmdname [param1, param2...]
Parameters:

cmdname: the name of the external command to execute
param1/2...: optional expressions passed to the external command

more...

less...

EXTERN (alias !) is used to execute commands external to Tiny Hexer Script. Currently it can be used to activate items of the Tiny Hexer main menu. To execute a main menu entry, prefix the name of the menu command by 'CMD.'. Some of the commands can make use of additional parameters (like a filename for the CMD.FileOpen command).

List of menu commands and their parameters
Sample:
= open a file in Tiny Hexer
EXTERN "CMD.FileOpen", 'c:\cmldr'
= alternative
!CMD.FileOpen 'c:\boot.ini'

= open a new editor window
!CMD.FileNew
FILECLOSE file
Parameters:

file: a variable of type FILE

more...

less...

The FILECLOSE command is used to close a file previously opened by FILEOPEN.
See also: FILEOPEN() function, FILEREAD, FILEWRITE.
Sample:
VAR f FILE, line TEXT

LET f = FILEOPEN('c:\autoexec.bat', 'r')
= opens the file c:\autoexec.bat for reading

FILEREADTEXTLINE f, line
= reads a line of text from the file

FILECLOSE f
= closes the file handle

MSGBOX ("Line: "+line)
= displays the line
FILEDELETE filename [, flags]
Parameters:

filename: an expression of type TEXT
flags: an optional expression of type BYTE

more...

less...

Use the FILEDELETE command to delete the file filename.

The optional flags parameter tells Tiny Hexer Script whether it should raise an error if the file to be deleted does not exist or cannot be deleted. If bit 0 (= value 1) of the flags parameter is not set, an error is raised if the file does not exist. If bit 1 (= value 2) is not set, an error is raised if the file cannot be deleted. Set flags to 3 to suppress all errors, set it to 0 (default) to check both conditions.
Sample:
= tries to delete the file, an error is raised if the file does not exist or cannot be deleted
FILEDELETE 'c:\test.tmp'

= tries to delete the file, don't care if the file does exist or can be deleted
FILEDELETE 'c:\test.tmp', 3
FILEREAD file, buffer [, count]
Parameters:

file: a variable of type FILE
buffer: a variable of type TEXT, CHAR, BYTE, WORD, DWORD or QWORD
count: an optional expression of type DWORD

more...

less...

Use the FILEREAD command to read data from the file file into the variable buffer.

The optional count parameter tells Tiny Hexer Script how many bytes of data are to be read. If this parameter is omitted, the type of buffer defines the amount of data to be read (BYTE, CHAR: 1 Byte, WORD: 2 Bytes, DWORD: 4 Bytes, QWORD: 8 Bytes, TEXT: reads from the file until EOF or a 0x00 byte is found).

If less data than expected has been read from the file, an error is raised. To avoid those errors (or if the exact amount of data that should be read from the file is unknown), use the FILEREAD() function instead of the command.
See also: FILEREAD() function, FILEWRITE, FILEOPEN() function, FILECLOSE, FILEREADTEXTLINE.
Sample:
VAR f FILE, wholedata TEXT

LET f = FILEOPEN('c:\autoexec.bat', 'r')
= opens the file c:\autoexec.bat for reading

FILEREAD f, wholedata
= reads all text from the file (only if no 0x00 byte is in the file)

FILECLOSE f
= closes the file handle

MSGBOX ("Contents: "+wholedata)
= displays the contents
FILEREADTEXTLINE file, txtbuffer
Parameters:

file: a variable of type FILE
txtbuffer: a variable of type TEXT

more...

less...

Use the FILEREADTEXTLINE command to read one line of text data from the file file into the text variable txtbuffer.

The end of a line is marked using 0x0a, 0x0d, 0x0a+0x0d or 0x0d+0x0a characters. Those line terminators are cut off from txtbuffer.
See also: FILEREAD.
Sample:
VAR f FILE, line TEXT

LET f = FILEOPEN('c:\autoexec.bat', 'r')
= opens the file c:\autoexec.bat for reading

FILEREADTEXTLINE f, line
= reads a line of text from the file

FILECLOSE f
= closes the file handle

MSGBOX ("Line: "+line)
= displays the line
FILESEEK file, position [, origin]
Parameters:

file: a variable of type FILE
position: an expression of type DWORD
origin: an optional expression of type DWORD

more...

less...

Use the FILESEEK command to move the position pointer of file file to position position manually. FILEREAD... and FILEWRITE automatically adjust a file's position pointer to the following byte. Using FILESEEK you can randomly acces data in a file.

If the optional parameter origin is present, the way of calculating the new position changes. Setting origin to 0 (= FILE_BEGIN) sets the position pointer of the file to the absolute value position (default). Setting it to 1 (= FILE_CURRENT) adds the value of position to the current position. Setting it to 2 (= FILE_END) set the file's position pointer to the value of position + the file's size.
See also: FILESIZE(), FILEPOS().
Sample:
VAR f FILE, line TEXT, fpos DWORD, fname TEXT

LET fname = 'c:\dttest.txt'

IF FILEEXISTS(fname)
  = open the file for reading and writing
  LET f = FILEOPEN(fname, 'rw')
ELSE
  = create the file
  LET f = FILEOPEN(fname, 'c')
ENDIF

= get current date and time
LET line = ENVPARSE('%date% - %time%')

= set the file pointer to the file's end
FILESEEK f, 0, 2

= append date/time string to the file
FILEWRITE f, (line+"\r\n")

FILECLOSE f
= closes the file handle
FILESETPROP file, property, value
Parameters:

file: a variable of type FILE
property: an expression of type TEXT
value: an expression

more...

less...

FILESETPROP is used to change a special file's properties. To set a file's properties, it must have been opened with read-write access. property is the name of the property to be modified, value is the property's new value. The type of value depends on the property.

List of available properties

See also: FILEGETPROP() function, FILEOPEN() function.
Sample:
VAR newed FILE

= open a new editor window
LET newed = FILEOPEN('::new', 'c')

= set bytes per row property to 12
FILESETPROP newed, 'BytesPerRow', 12

= close the file
FILECLOSE newed
FILEWRITE file, data1 [, data2...]
Parameters:

file: a variable of type FILE
data1/2...: expressions of type TEXT, CHAR, BYTE, WORD, DWORD or QWORD

more...

less...

Use the FILEWRITE command to write the contents of data1/2... to the file file.

The type of the data... expressions define the amount of data to be written to the file (BYTE, CHAR: 1 Byte, WORD: 2 Bytes, DWORD: 4 Bytes, QWORD: 8 Bytes, TEXT: length of the text value).

If less data than expected has been written to the file, an error is raised. To avoid those errors, use the FILEWRITE() function instead of the command.
See also: FILEWRITE() function, FILEREAD, FILEOPEN() function, FILECLOSE.
Sample:
VAR f FILE, line TEXT, fpos DWORD, fname TEXT
LET fname = 'c:\test.txt'

= enter a line of text
LET line = INPUT('Enter a line of text')

= create the file
LET f = FILEOPEN(fname, 'c')

= write line to the file
FILEWRITE f, (line+"\r\n")

FILECLOSE f
= closes the file handle
GOTO target
Parameters:

target: name of a label in the current script

more...

less...

GOTO continues script execution at the position marked with the label target.

Contrary to the CALL command, GOTO doesn't store the current script position before going to the marked command, so the RETURN command cannot be used to return from the subroutine.
See also: CALL, LABEL.
Sample:
= goto the end of the script
GOTO end_of_script

= the following command is never executed
MSGBOX "This message will never be shown"

LABEL end_of_script
END
IF condition : ifblock [ : ELSE : elseblock] : ENDIF
Parameters:

condition: a numeric expression
ifblock, elseblock: a sequence of Tiny Hexer Script commands

more...

less...

IF... commands are used to execute a sequence of commands (ifblock) only if the numeric expression condition equals to a value other than 0.

If the optional ELSE branch is present, the elseblock command sequence is executed otherwise.

The ENDIF statement terminates the ifblock resp. the elseblock sequence.
See also: REPEAT...UNTIL, WHILE...ENDWHILE.
Sample:
= decimal number to text
LET NUMBER_RADIX = 10
LET NUMBER_PREFIX = ''
LET NUMBER_SUFFIX = ''

MSGBOX "Guess a number game", 64

VAR number BYTE, entered BYTE

LABEL start

= randomly choose a number between 1 and 10
LET number = RANDOM(10)+1

LABEL loop

LET entered = BYTE(INPUT('Enter a number between 1 and 10'))
IF entered == number
  MSGBOX 'Right!'
ELSE
  IF number < entered
    MSGBOX ('My number is less than '+TEXT(entered))
  ELSE
    MSGBOX ('My number is greater than '+TEXT(entered))
  ENDIF
  GOTO loop
ENDIF

GOTO start
IFGOTO srcexpr, expr1, target1 [ , expr2, target2...]
Parameters:

srcexpr, expr1, expr2...: expressions
target1, target2...: labels in the current script

more...

less...

The IFGOTO command checks whether the value of one of the expressions expr1, expr2... is equal to the source expression srcexpr. if a match is found, the script is continued at the corresponding label (target1, target2...).
Sample:
VAR a byte

a = DWORD(INPUT('Enter a number between 1 and 5'))
IFGOTO a, 1, label1, 2, label2, 3, label3, 4, label4, 5, label5

= none of the allowed numbers has been entered, bail
ERROR 'Wrong number entered!'

VAR t TEXT

= make text from number
@@label1:t = 'one':GOTO labelout
@@label2:t = 'two':GOTO labelout
@@label3:t = 'three':GOTO labelout
@@label4:t = 'four':GOTO labelout
@@label5:t = 'five'

= output text number
@@labelout
MSGBOX t
INC numvar, numexpr
Parameters:

numvar: the name of a numeric variable (CHAR, BYTE, WORD, DWORD, QWORD)
numexpr: a numeric expression

more...

less...

INC adds the value of the numeric expression numexpr to the value already stored in the numeric variable numvar. (Note: The INC command is faster than the numeric '+' operator.)
See also: numeric '+' operator, CONCAT.
Sample:
VAR number DWORD

= variable number is set to the value 10
LET number = 10

INC number, 20
= variable number now contains the value 30.
INCLUDE 'filename'
Parameters:

filename: filename of the script to be included

more...

less...

The INCLUDE statement is similar to #include in the C programming language. It is used to replace itself by the contents of another script file. The syntax is very strict: The Include command must be the only command in its text line, the filename must be written literally in single quotes and between the INCLUDE statement and the first quote must be exactly one blank character. If the filename does not contain a path, the standard include path (<tiny hexer application path>\scripts\inc) is searched for the given filename.
Sample:
= include the standard definitions in def.mps
INCLUDE 'def.mps'

= show a warning message box
= MB_ICONWARNING is defined in def.mps
MSGBOX 'Warning!', MB_ICONWARNING
INIWRITE filename, section [, key [,value]]
Parameters:

filename, section, key: TEXT expressions
value: an expression

more...

less...

Use the INIWRITE command to write data to ini-style text files.

filename is the name of the ini file.
section is the name of the section in the ini file ([section] lines).
key is the name of the key in the ini file (the part to the left of the equal sign).
value is the data of the key (the part to the right of the equal sign).

If key and value are omitted, the whole section section is removed from the ini file.

If value is omitted, key is removed from section section in the ini file.
See also: INIREAD() function.
Sample:
DEF ini "c:\\mpthtest.ini"

= write some values to the ini file
iniwrite ini, "section 1", "key 1", 2
iniwrite ini, "section 1", "key 2", "abc"
iniwrite ini, "section 2", "key 1", 2
iniwrite ini, "section 2", "key 2", "abc"

= remove section 2 from the ini file
iniwrite ini, "section 2"

= remove section 1/key 2 from the ini file
iniwrite ini, "section 1", "key 2"

VAR val DWORD

= try to read the section 1/key 1
IF INIREAD(ini, "section 1", "key 1", @val)
  MSGBOX ('Value of section 1/key 1: '+TEXT(val))
ELSE
  ERROR ('Cannot read section 1/key 1 value from '+ini)
ENDIF
LABEL name
@@name
Parameters:

name: name of the label

more...

less...

The LABEL statement (alias @@) marks the following command with the identifier name, so the CALL, GOTO and LOOP commands can "jump" to this position.
See also: CALL, GOTO, LOOP.
Sample:
INCLUDE 'def.mps'
MSGBOX "To stop this script, press the 'Alt' key", MB_ICONINFORMATION

= mark the first command with 'start'
LABEL start

= infinite loop
GOTO start

= alternate syntax
@@start1

= infinite loop
GOTO start1
LET var = expr
var = expr
Parameters:

var: variable
expr: expression

more...

less...

The LET command is used to assign the value of expression expr to the variable var. This assignment succeeds only if the data types of var and expr are compatible.

Variables must be defined using the VAR command before data can be assigned to them.

In unambigous cases, the LET keyword may be omitted.
See also: Variables, VAR, Type compatibility.
Sample:
= define some variables
VAR t1 TEXT, c1 CHAR, b1 BYTE, d1 DWORD

= success
LET t1 = c1
c1 = t1

b1 = d1
LET d1 = b1

= because the CHAR type is compatible to numeric and text data types,
= the following assignments also will succeed
LET b1 = c1
LET c1 = d1

= to assign incompatible data types, use the conversion functions
LET t1 = TEXT(b1)
LET t1 = '0':LET d1 = DWORD(t1)

= these assignments will fail
LET t1 = b1
LET d1 = t1
LOOP target, count
Parameters:

target: the name of a label in the current script
count: expression of type DWORD

more...

less...

LOOP calls the subroutine marked with the label target count times. During subroutine execution, the current loop index can be retrieved by reading the special variable LOOP.

Contrary to the CALL command, no additional parameters can be passed to the subroutine. Use the PUSH command to store parameters on the stack.
See also: LOOP special variable, CALL, RETURN.
Sample:
= factorial function
INCLUDE 'def.mps'
OPTION GLOBALVARS, 1
LET NUMBER_RADIX = 10
LET NUMBER_PREFIX = ''
LET NUMBER_SUFFIX = ''

VAR b BYTE
VAR res QWORD

LABEL start
LET b = BYTE(INPUT('Factorial function', 'Enter a number between 1 and 20'))
IF (b < 1) OR (b > 20): GOTO start: ENDIF

LET res = 0
LOOP factorial, (b+1)

MSGBOX ('!'+TEXT(b)+' = '+TEXT(res)), MB_ICONASTERISK, 'Factorial function'
END

LABEL factorial
IF loop == 0
  LET res = 1
ELSE
  LET res = res * loop
ENDIF
RETURN
MSGBOX message [, flags [, title]]
Parameters:

message: expression of type TEXT
flags: optional expression of type DWORD
title: optional expression of type TEXT

more...

less...

MSGBOX shows a dialog displaying the text message.

The optional flags parameter tells Windows to change the behaviour and/or appearance of the dialog (see MSGBOX flags). If you want to show a message box containing more than one button, you should use the MSGBOX() function to retrieve the button clicked by the user.

The optional title parameter modifies the title bar caption of the message dialog.
See also: TEXTBOX, MSGBOX() function.
Sample:
INCLUDE 'def.mps'

= show an info message
MSGBOX 'Info message', MB_ICONINFORMATION

= show a warning message using a different title
MSGBOX 'Warning message', MB_ICONWARNING, 'Warning title'

= show an error message with 'yes' and 'no' buttons
MSGBOX 'Error message', (MB_ICONERROR OR MB_YESNO)
OPTION statement (see Directives)
POP var
Parameters:

var: a variable

more...

less...

POP returns a data stored on the stack and assigns it to the variable var. The data is removed from the stack. The data type depends on the data on the stack. Data can be pushed to the stack using the CALL and PUSH commands.

In Tiny Hexer Script, the stack is a LIFO (last in first out), so when pushing the text "A" first and after this the numeric value 200 to the stack, POP returns 200 on the first and "A" on the second call. The stack can hold up to 4095 data values at a time.
See also: CALL, PUSH.
Sample:
VAR t1 TEXT,  t2 TEXT

= pushes 'first', than 'second' to the stack and calls the label concat
CALL concat, "first", "second"

= use the END command to avoid running into the subroutine again
END

LABEL concat
POP t1
= t1 now contains 'second' (the last parameter pushed to the stack)

POP t2
= t2 now contains 'first' (the last-but-one parameter pushed to the stack)

= displays the message 'second first' !!!
MSGBOX t1+" "+t2

= return from the subroutine
RETURN
PUSH param1 [, param2...]
Parameters:

param1/2...: expressions

more...

less...

PUSH stores all its parameters param1/2... to the stack. To restore data pushed to the stack, use the POP command.

In Tiny Hexer Script, the stack is a LIFO (last in first out), so when pushing the text "A" first and after this the numeric value 200 to the stack, POP returns 200 on the first and "A" on the second call. The stack can hold up to 4095 data values at a time.
See also: POP.
Sample:
= exchange vars example
VAR t1 TEXT,  t2 TEXT

t1 = 'first'
t2 = 'second'

= now exchange the two variables using the stack as temporary storage
PUSH t1, t2
POP t1
POP t2

= t1 now contains the text 'second', t2 now contains the text 'first'
REPEAT : block : UNTIL condition
Parameters:

block: a sequence of Tiny Hexer Script commands
condition: a numeric expression

more...

less...

REPEAT...UNTIL commands are used to execute a sequence of commands (block) as long as the numeric expression condition equals to 0.

Contrary to the WHILE...ENDWHILE command, the block command sequence is always executed at least once.
See also: IF...ELSE...ENDIF, WHILE...ENDWHILE.
Sample:
INCLUDE 'def.mps'

VAR button DWORD

= enter the loop
REPEAT
  button = MSGBOX('Leave this loop?', MB_YESNO or MB_ICONQUESTION or MB_DEFBUTTON2)

  = leave the loop only if the user clicked the IDYES button
UNTIL button == IDYES
RETURN

more...

less...

Use the RETURN command to end a subroutine executed by CALL or LOOP and return to the command following the calling.
See also: CALL, LOOP, OPTION GLOBALVARS directive.
Sample:
MSGBOX "Main block"

CALL Sub1
MSGBOX "Main block again"
END

@@Sub1
MSGBOX "Subroutine block"
RETURN
SHELL program [, parameters [, show [, directory [, wait]]]]
Parameters:

program, parameters, directory: expressions of type TEXT
show: an expression of type DWORD
wait: an expression of type BYTE

more...

less...

The SHELL command is used to execute the external application program.

Optionally the command line arguments parameters can be passed to program.

Additionally you can tell Tiny Hexer Script to show or hide the external application using the show parameter (SW_HIDE, SW_SHOW...)

The optional directory parameter tells Windows to set program's current directory.

The optional wait flag tells Tiny Hexer Script whether to wait until the external program has finished (1) or not (0, this is the default).
See also: SHELL() function.
Sample:
= open autoexec.bat in editor in maximized state
INCLUDE 'def.mps'

SHELL 'Notepad.exe', 'c:\autoexec.bat', SW_SHOWMAXIMIZED
SHOWPROGRESS
SHOWPROGRESS percentage
SHOWPROGRESS max, current
Parameters:

percentage: an expression of type BYTE
max, current: expressions of type DWORD

more...

less...

The SHOWPROGRESS command is used to control the progress indicator on the status bar of Tiny Hexer's main window.

SHOWPROGRESS without parameters hides the progress indicator.

SHOWPROGRESS percentage sets the progress indicator to the value percentage (0..100). A value greater than 99 hides the progress indicator.

SHOWPROGRESS max, current lets Tiny Hexer calculate the percentage itself. If current is equal to or greater than max (percentage >= 100), the progress indicator is hidden.
Sample:
= show a progress value of 50 percent
SHOWPROGRESS 50
MSGBOX "50% progress"

= show a progress of 75 percent (150/200 = 0.75)
SHOWPROGRESS 200, 150
MSGBOX "75% progress ((150 / 200) * 100)"

= hide the progress bar
SHOWPROGRESS
TAGVAR var, [tag_pos], [tag_len]
Parameters:

var: a variable
tag_pos, tag_len: expressions of type DWORD

more...

less...

Use the TAGVAR command to set, modify or remove tags of variables. Tagged variables are used in the Structure Viewer to display hyperlinks in the browser window.

If either the tag_pos or the tag_len parameter is empty, the corresponding tag part of var remains unchanged.

If both tag_pos and tag_len are empty, var is untagged.
See also: Variable Tagging, COPYTAGS, TAG_POS() function, TAG_LEN() function, OPTION READTAGS directive.
Sample:
= TAGVAR example:
=
= display a hyperlink in the browser window that selects the first 7 bytes in the
= current editor
=
= NOTE: This sample script must be loaded into the structure viewer!

VAR browser FILE

= open a file to the browser structview browser window to write the data
browser = FILEOPEN('::browser','c')

VAR hyper TEXT

LET hyper = "Select the first seven bytes in the current editor.\n\n"

= 0: position of link-block
= 7: length of link-block
TAGVAR hyper, 0, 7

FILEWRITE browser, hyper

LET hyper = "This text is not a hyperlink."

= untag the variable
TAGVAR hyper, ,

FILEWRITE browser, hyper

= close the browser file
FILECLOSE browser
TEXTBOX text, [title]
Parameters:

text, title: expressions of type TEXT

more...

less...

The TEXTBOX command is used to display a (multiline) text in a modal window. This text can be copied to the clipboard and/or saved to disk.

text is the text to display.

title is the optional caption of the message window's title bar. If this parameter is omitted, a default title is used.
See also: MSGBOX.
Sample:
= TEXTBOX example:
=
= read the directory C:\ via the shell and show the dir list
= using the TEXTBOX command

VAR msg TEXT

IF (SHELL(ENVPARSE('%comspec%'), '/k DIR', 0, 'C:\', @msg) != 0)
  ERROR "Cannot execute shell"
ENDIF

TEXTBOX msg, "Directory List"
VAR name type [, name type...]
Parameters:

name: name of the variable to be declared
type: type of the variable to be declared

more...

less...

The VAR command declares the variable name and tells Tiny Hexer Script its data type.

variables can be declared only once, they must be declared before other commands can use them.
See also: Variables, Data Types, OPTION GLOBALVARS directive.
Sample:
= declare a text and a number (Byte) variable
VAR msg TEXT, num BYTE

= assign a value
LET msg = 'Hello'

= show message
MSGBOX msg

= the following does not work as num is not of type text
LET num = 'Hello'
WHILE condition : block : ENDWHILE
Parameters:

condition: a numeric expression
block: a sequence of Tiny Hexer Script commands

more...

less...

WHILE...ENDWHILE commands are used to execute a sequence of commands (block) as long as the numeric expression condition does not equal to 0.

Contrary to the REPEAT...UNTIL command, the block command is not executed at all if condition equals to 0.
See also: IF...ELSE...ENDIF, REPEAT...UNTIL.
Sample:
= the command between WHILE...ENDWHILE will never be executed
WHILE 0 == 1
  MSGBOX 'This message will never be shown!'
ENDWHILE

===============================================

VAR num BYTE
LET num = 0
WHILE num != 8
  INC num, 1
ENDWHILE

MSGBOX ("Number is: "+TEXT(num))


Tiny Hexer Script: Functions

This page shows all available Tiny Hexer Script functions.
A B C D E F H I M P Q R S T W
BYTE ASKFINDOPTIONS(caption, searchdata_ref, istext_ref, ignorecase_ref, wildcard_ref)
Parameters:

caption: a TEXT expression
searchdata_ref, istext_ref, ignorecase_ref, wildcard_ref: expressions of type VARREF

more...

less...

Use the ASKFINDOPTIONS() function to let the user choose search options in a find dialog.

If the User clicks the Cancel button, the function returns 0, otherwise 1 is returned and the find options are stored in the variables referenced by the *_ref expressions:

searchdata_ref must refer to a TEXT variable that will be set to the text to search for.

istext_ref must refer to a BYTE variable set to the value of the "Find Text" and "Regular Expression" checkboxes (2 if "Regular Expression" is checked, 1 if "Find Text" is checked, 0 otherwise).

ignorecase_ref must refer to a BYTE variable set to the value of the "Ignore Case" checkbox.

wildcard_ref must refer to a TEXT variable that is set to the wildcard text if the user checked the "Wildcard" checkbox, otherwise, it's set to an empty string.
Sample:
= search for all occurences of a string in the current file, store
= the results in the position list and save the positions list to disk

= query find options
var f_Text TEXT, f_FindText BYTE, f_IgnoreCase BYTE, f_Wildcard TEXT
if (not AskFindOptions("Search the whole file and save results", @f_Text, @f_FindText, @f_IgnoreCase, @f_Wildcard))
  end
endif

= query file name for list saving
var res_file TEXT
res_file = AskSaveFileName("Choose name of search results file", 'Text Files (*.txt)|*.txt')

= clear current contents of the position list
if (POSITION_COUNT)
  !CMD.PosListSelectAll
  !CMD.PosListDeleteSelected
endif

= find all and store in the position list
!CMD.EditFindStore f_text, f_ignorecase, f_findtext, f_wildcard

if (not POSITION_COUNT)
  = not found
  error "Data not found!"
else
  = save
  POSITION_DESC = ("Search results for: "+f_text+" on "+CURRENTFILE)
  !CMD.PosListSave res_file
endif
TEXT ASKOPENFILENAME([caption [, filter]])
Parameters:

caption, filter: optional TEXT expressions

more...

less...

Use the ASKOPENFILENAME() function to let the user select a filename for file loading.

The optional caption parameter sets the title of the file selection dialog.

The optional filter parameter tells Tiny Hexer what file types to display in the file selection dialog. This parameter is a TEXT string in the form of "Description|File mask[|...]" (e.g. "Text files|*.txt|All files|*.*").

Note: If the user chooses the "Cancel" button in the file dialog, script execution is terminated.
See also: ASKSAVEFILENAME().
Sample:
= select a file and print it via notepad
VAR fname TEXT

LET fname = ASKOPENFILENAME('Print a Text file', 'Text Files (*.txt)|*.txt')

SHELL 'notepad.exe',  ('/p "'+fname+'"')
TEXT ASKSAVEFILENAME([caption [, filter]])
Parameters:

caption, filter: optional TEXT expressions

more...

less...

Use the ASKSAVEFILENAME() function to let the user select a filename for file storing.

The optional caption parameter sets the title of the file selection dialog.

The optional filter parameter tells Tiny Hexer what file types to display in the file selection dialog. This parameter is a TEXT string in the form of "Description|File mask[|...]" (e.g. "Text files|*.txt|All files|*.*").

Note: If the user chooses the "Cancel" button in the file dialog, script execution is terminated.
See also: ASKOPENFILENAME().
Sample:
= save the current selection to disk
VAR selname TEXT

IF CURRENTFILE == ''
  ERROR 'No open file'
ENDIF

LET selname = ASKSAVEFILENAME('Save current selection', 'All Files (*.*)|*.*')

!CMD.FileSaveSelection selname
BYTE BYTE(expr)
Parameters:

expr: an expression

more...

less...

The BYTE() function is used to convert the expression expr to the BYTE data type.

If expr is a numeric or CHAR expression, the lowest eight bits of its value are returned.

If expr is of type TEXT, Tiny Hexer tries to convert the text string to a number. If conversion fails, an error is raised. If conversion succeeds, the lowest eight bits of the converted number are returned.
See also: Data types, CHAR(), DWORD(), QWORD(), TEXT(), WORD().
Sample:
= show the ascii value of a char
VAR ch CHAR inp TEXT bt BYTE

REPEAT
  inp = INPUT('Enter a character', '', 'A')
UNTIL TEXTLEN(inp) == 1

LET ch = inp

LET bt = BYTE(ch)

MSGBOX ('The ASCII value of '+inp+' is '+TEXT(bt))
CHAR CHAR(expr)
Parameters:

expr: an expression

more...

less...

The CHAR() function is used to convert the expression expr to the CHAR data type.

If expr is a numeric expression, the lowest eight bits of its value are converted to a character and are returned.

If expr is of type TEXT, the first character of the string is returned. If the string is empty, an error is raised.
See also: Data types, BYTE(), DWORD(), ISNUMBER(), QWORD(), TEXT(), WORD().
Sample:
= show the character representing an ascii value
VAR ch CHAR num BYTE inp TEXT

REPEAT
  REPEAT
    inp = INPUT('Enter an ASCII value between 33 and 127', '', '65')
  UNTIL ISNUMBER(inp)
  LET num = BYTE(inp)
UNTIL (num > 32) AND (num < 128)

LET ch = CHAR(num)

MSGBOX ('Character: "'+ch+'"')
DWORD COMPARE_END(index)
Parameters:

index: a numeric expression

more...

less...

The COMPARE_END() function returns the position of the last byte of difference block #index (first block is at index 0) after a file comparison has been executed.
See also: File Comparison, COMPARE_COUNT special variable, COMPARE_START().

DWORD COMPARE_START(index)
Parameters:

index: a numeric expression

more...

less...

The COMPARE_START() function returns the position of the first byte of difference block #index (first block is at index 0) after a file comparison has been executed.
See also: File Comparison, COMPARE_COUNT special variable, COMPARE_END().

TEXT DATA2TEXT(expr)
Parameters:

expr: an expression

more...

less...

The DATA2TEXT() function is used to store the binary value of expression expr in a data of type TEXT.

It e.g. can be used to create tables of multiple numeric values by storing them in a single TEXT string.
See also: TEXT2DATA().
Sample:
= power of 2 table example
INCLUDE 'def.mps'
NUMBER_RADIX = 10
NUMBER_PREFIX = ''
NUMBER_SUFFIX = ''

VAR ptable TEXT, num QWORD
VAR inp TEXT q QWORD power QWORD
OPTION GLOBALVARS, 1

LET num = 1
LET ptable = ''
LOOP create_table 63

REPEAT
  REPEAT
    REPEAT
      LET inp = INPUT('Enter a number between 0 and 62')
    UNTIL ISNUMBER(inp)
    LET q = QWORD(inp)
  UNTIL (q < 63) AND (q >= 0)

  = power values are stored as QWORD, so QWORD_SIZE must be used
  = to access the correct data
  power = TEXT2DATA(ptable, q, QWORD_SIZE)
  MSGBOX ( '2 ** '+TEXT(q)+' = '+TEXT(power))

UNTIL 0

END

= store the next power of 2 as QWORD in ptable
@@create_table
CONCAT ptable, DATA2TEXT(QWORD(num))
INC num, num
RETURN
VAR DEREF(reference)
Parameters:

reference: a variable of type VARREF

more...

less...

The DEREF() function is used to retrieve the referenced variable stored in reference.

The function is used to e.g. pass data of arbitrary data types to a subroutine. To create references to variables, use the unary reference operator @.
See also: VARREF data type, unary reference operator @, TYPEOF().
Sample:
= show data type example
INCLUDE 'def.mps'

VAR c CHAR, b BYTE, w WORD, d DWORD, q QWORD, t TEXT, f FILE, n NONE

CALL dt @c : CALL dt @b : CALL dt @w : CALL dt @d
CALL dt @q : CALL dt @t : CALL dt @f : CALL dt @n

END

VAR type BYTE, ref VARREF

@@dt

POP ref
LET type = TYPEOF(DEREF(ref))

IF type == CHAR_DATA
  MSGBOX 'Char data'
ELSE
  IF type == BYTE_DATA
    MSGBOX 'Byte data'
  ELSE
    IF type == WORD_DATA
      MSGBOX 'Word data'
    ELSE
      IF type == DWORD_DATA
        MSGBOX 'DWord data'
      ELSE
        IF type == QWORD_DATA
          MSGBOX 'QWord data'
        ELSE
          IF type == TEXT_DATA
            MSGBOX 'TEXT String data'
          ELSE
            IF type == FILE_DATA
              MSGBOX 'File data'
            ELSE
              IF type == VARREF_DATA
                MSGBOX 'Variable reference'
              ELSE
                MSGBOX 'Empty data'
              ENDIF
            ENDIF
          ENDIF
        ENDIF
      ENDIF
    ENDIF
  ENDIF
ENDIF

RETURN
DWORD DWORD(expr)
Parameters:

expr: an expression

more...

less...

The DWORD() function is used to convert the expression expr to the DWORD data type.

If expr is a numeric or CHAR expression, the lowest 32 bits of its value are returned.

If expr is of type TEXT, Tiny Hexer tries to convert the text string to a number. If conversion fails, an error is raised. If conversion succeeds, the lowest 32 bits of the converted number are returned.
See also: Data types, BYTE(), CHAR(), QWORD(), TEXT(), WORD().
Sample:
= convert a text to a dword number
VAR inp TEXT dw DWORD

REPEAT
  inp = INPUT('Enter a numeric value')
UNTIL ISNUMBER(inp)

LET dw = DWORD(inp)

= output hexadecimal
MSGBOX ('The number you entered was (hex): '+TEXT(dw))
TEXT ENVPARSE(string)
Parameters:

string: an expression of type TEXT

more...

less...

The ENVPARSE() function expands all environment variables in string to their actual values. Environment variables must be enclosed in percent signs (%).

Three special variables do exist:
  • %APPPATH%: Expands to the name of the directory where Tiny Hexer resides
  • %DATE%: Expands to the current date
  • %TIME%: Expands to the current time
Sample:
= show current date and time
MSGBOX (ENVPARSE('Current Date: %date%, Current Time: %time%'))
TEXT EXTRACTPATH(name)
Parameters:

name: an expression of type TEXT

more...

less...

The EXTRACTPATH() function returns the path part of name including the trailing backslash.
See also: EXTRACTNAME().
Sample:
VAR fname TEXT, fpath TEXT

LET fname = ASKOPENFILENAME('Select a file')
LET fpath = EXTRACTPATH(fname)
LET fname = EXTRACTNAME(fname)

MSGBOX ('The file '+fname+' is in directory '+fpath)
TEXT EXTRACTNAME(name)
Parameters:

name: an expression of type TEXT

more...

less...

The EXTRACTNAME() function returns the filename part of name without the preceding path.
See also: EXTRACTPATH().
Sample:
VAR fname TEXT, fpath TEXT

LET fname = ASKOPENFILENAME('Select a file')
LET fpath = EXTRACTPATH(fname)
LET fname = EXTRACTNAME(fname)

MSGBOX ('The file '+fname+' is in directory '+fpath)
BYTE FILEEXISTS(filename)
Parameters:

filename: an expression of type TEXT

more...

less...

The FILEEXISTS() function returns 1 if the file filename exists, otherwise 0 is returned.
Sample:
VAR fname TEXT

LET fname = INPUT('Enter a filename to open in Tiny Hexer')

IF FILEEXISTS(fname)
  !CMD.FileOpen fname
ELSE
  ERROR ('File '+fname+' not found')
ENDIF
VALUE FILEGETPROP(file, property)
Parameters:

file: a variable of type FILE
property: an expression of type TEXT

more...

less...

FILEGETPROP() is used to retrieve a property of a special file.

The data type of the returned value depends on the property.

List of available properties

See also: FILESETPROP command, FILEOPEN().
Sample:
VAR ed FILE, val BYTE

= open the current editor window
LET ed = FILEOPEN('::current', 'r')

= get bytes per row
LET val = FILEGETPROP(ed, 'BytesPerRow')

= close the file
FILECLOSE ed

LET NUMBER_RADIX = 10
LET NUMBER_PREFIX = ''
LET NUMBER_SUFFIX = ''

= show the BytesPerRow property
MSGBOX ('Current editor displays '+TEXT(val)+' Bytes per row')
FILE FILEOPEN(filename, mode)
Parameters:

filename, mode: expressions of type TEXT

more...

less...

Use FILEOPEN() to attach file filename to a FILE type variable.

The mode parameter tells Tiny Hexer Script how to open the file and what access to grant to the file's contents. This parameter must be a combination of one or more of the following characters:
  • "c": always create the file, erase its contents if it already exists. This mode flag also implies write access to the file
  • "r": grant read access to the file's contents (default)
  • "w": grant write access to the file's contents
Special Files:
In Tiny Hexer there are numerous special files. To distinguish special files from ordinary files, the filename parameter must be start with a double colon "::". The following special files exist in Tiny Hexer:
  • "::Clipboard": open clipboard contents (CF_TEXT format)
  • "::Browser": open the Structure Viewer browser window, so you can write text to the browser. Note: The mode parameter must be set to "c". You cannot read from this file, and also random write access to this file is not possible, only sequential write access is supported
  • "::New": open a new editor window and get access to this editor's data
  • "::Current": open a handle to the data of the currently active editor. If another editor window becoms active, the file remains attached to the editor which was active at the time the file has been opened
  • "::Editor": open a handle to the data of the currently active editor. If another editor window becoms active, the file will be attached to the newly activated editor.
  • "::<filename>": attaches the file to the editor data whose window caption matches <filename>
See also: FILECLOSE command, FILEREAD(), FILEWRITE().
Sample:
= sample: read a file from disk and write its contents to a new
= editor window, xoring each byte by 255
VAR ed FILE, f FILE, b BYTE sz DWORD lp DWORD

= open the file on disk (readonly "r")
LET f = FILEOPEN(ASKOPENFILENAME('Select a file'), 'r')

= open a new editor window
LET ed = FILEOPEN('::new', 'c')

LET sz = FILESIZE(f)
LET lp = 0

= set datasize of editor to file's size
FILESETPROP ed, 'Size', sz
= Changing the size sets the file pointer to eof, so reset
FILESEEK ed, 0

= read and transform the file's contents and write the data to the editor
WHILE FILEREAD(f, @b)
  SHOWPROGRESS sz, lp
  INC lp, 1
  LET b = b XOR 255
  FILEWRITE ed, b
ENDWHILE

= close the file handles
FILECLOSE ed
FILECLOSE f
DWORD FILEPOS(file)
Parameters:

file: file type variable

more...

less...

The FILEPOS() returns the current position pointer of file.
See also: FILESEEK command, FILEREAD(), FILESIZE(), FILEWRITE().
Sample:
INCLUDE 'def.mps'
NUMBER_RADIX=10
NUMBER_PREFIX=''
NUMBER_SUFFIX=''

VAR Position DWORD mpth FILE

= open tiny hexer itself in a new editor window
!CMD.FileOpen ENVPARSE('%apppath%\mpth.exe')

= attach a file to the editor, only read access is needed
mpth=FILEOPEN('::current', 'r')

Position=FILEPOS(mpth)

= show start position (0)
MSGBOX ("Position at start of file (= 0): "+TEXT(Position)), (MB_OK OR MB_ICONINFORMATION)

= seek to file end
FILESEEK mpth, 0, FILE_END
= set cursor to end of file
!CMD.EditGoto '>0'

Position=FILEPOS(mpth)

= show end position (0)
MSGBOX ("Position at end of file (= file size): "+TEXT(Position)), (MB_OK OR MB_ICONINFORMATION)
DWORD FILEREAD(file, buffer [, count])
Parameters:

file: a variable of type FILE
buffer: an expression of type VARREF
count: an optional expression of type DWORD

more...

less...

Use the FILEREAD() function to read data from the file file into the variable referenced by buffer.

The optional count parameter tells Tiny Hexer Script how many bytes of data are to be read. If this parameter is omitted, the type of the variable referenced by buffer defines the amount of data to be read (BYTE, CHAR: 1 Byte, WORD: 2 Bytes, DWORD: 4 Bytes, QWORD: 8 Bytes, TEXT: reads from the file until EOF or a 0x00 byte is found).

FILEREAD() returns the actual amount of data (in Bytes) that was read from the file.
See also: FILEREAD command, FILEWRITE().
Sample:
VAR f FILE, wholefile TEXT, amount DWORD
NUMBER_RADIX=10
NUMBER_PREFIX=''
NUMBER_SUFFIX=''

= open the file c:\autoexec.bat for reading
LET f = FILEOPEN('c:\autoexec.bat', 'r')

= read up to 500000 bytes from the file
amount=FILEREAD(f, @wholefile, 500000)

= close the file handle
FILECLOSE f

= tell how many data has been read
MSGBOX ("Bytes read: "+TEXT(amount))
TEXT FILES(index)
Parameters:

index: expression of type DWORD

more...

less...

The FILES() function returns the filename of the editor child #index (first file is at index 0). Use the FILE_COUNT special variable to get the number of files currently opened in Tiny Hexer.
See also: FILE_COUNT special variable.
Sample:
= enumerate all open editor files

VAR d DWORD
VAR ed TEXT
NUMBER_RADIX=10
NUMBER_PREFIX=''
NUMBER_SUFFIX=''

d=FILE_COUNT
IF d == 0
  MSGBOX "No files open"
ELSE
  LOOP enum d
ENDIF
END

@@enum
ed=FILES(loop)
MSGBOX ("File "+TEXT(loop+1)+": "+ed)
RETURN
DWORD FILESIZE(file)
Parameters:

file: file type variable

more...

less...

The FILESIZE() returns the size (in Bytes) of file.
See also: FILESEEK command, FILEPOS().
Sample:
INCLUDE 'def.mps'
NUMBER_RADIX=10
NUMBER_PREFIX=''
NUMBER_SUFFIX=''

VAR Size DWORD mpth FILE

= open tiny hexer itself in a new editor window
!CMD.FileOpen ENVPARSE('%apppath%\mpth.exe')

= attach a file to the editor, only read access is needed
mpth=FILEOPEN('::current', 'r')

Size=FILESIZE(mpth)

MSGBOX ("Size of file: "+TEXT(Size)), (MB_OK OR MB_ICONINFORMATION)
DWORD FILEWRITE(file, data)
Parameters:

file: a variable of type FILE
data: an expression of type TEXT, CHAR, BYTE, WORD, DWORD or QWORD

more...

less...

Use the FILEWRITE() function to write the contents of data to the file file.

The type of the data expression defines the amount of data to be written to the file (BYTE, CHAR: 1 Byte, WORD: 2 Bytes, DWORD: 4 Bytes, QWORD: 8 Bytes, TEXT: length of the text value).

FILEWRITE() returns the actual amount of data (in Bytes) that has been written.
See also: FILEWRITE command, FILEREAD().
Sample:
INCLUDE 'def.mps'

VAR f FILE, dw DWORD, written DWORD, fname TEXT l TEXT
LET fname = 'c:\test.dat'

= enter a number
REPEAT
  l = INPUT('Enter a number')
UNTIL ISNUMBER(l)
LET dw=DWORD(l)

= create the file
LET f = FILEOPEN(fname, 'c')

= write the number in binary format
LET written=FILEWRITE(f, dw)

= close the file handle
FILECLOSE f

= check if all data has been written
IF written != DWORD_SIZE
  ERROR "Not all data could be written!"
ENDIF
QWORD HEX2NUM(digits)
Parameters:

digits: an expression of type TEXT

more...

less...

The HEX2NUM() function is used to convert the TEXT expression digits (consisting of hexadecimal digits) to a number.
See also: ISHEX().
Sample:
VAR i QWORD

LET i=HEX2NUM('FCE2')

= i is 64738 now
BYTE INIREAD(filename, section, key, buffer)
Parameters:

filename, section, key: expressions of type TEXT
buffer: VARREF

more...

less...

Use the INIREAD() function to read values from ini-style text files.

filename is the name of the ini file.
section is the name of the section in the ini file ([section] lines).
key is the name of the key in the ini file (the part to the left of the equal sign).
buffer is a reference to a variable that will contain the value read from the ini file.

If the specified key could be read from the ini file, 1 is returned. Otherwise 0 is returned.
See also: INIWRITE command.
Sample:
DEF ini "c:\\mpthtest.ini"

= write some data to the ini file
iniwrite ini, "section", "key1", 2
iniwrite ini, "section", "key2", "abc"

VAR val DWORD val_t TEXT

= try to read section/key1 as dword
IF INIREAD(ini, "section", "key1", @val)
  MSGBOX ('Value of section/key1: '+TEXT(val))
ELSE
  ERROR ('Cannot read section/key1 value from '+ini)
ENDIF

= try to read section/key2 as text
IF INIREAD(ini, "section", "key2", @val_t)
  MSGBOX ('Value of section/key2: '+val_t)
ELSE
  ERROR ('Cannot read section/key2 value from '+ini)
ENDIF
TEXT INPUT(prompt)
TEXT INPUT(caption, prompt [,default])
Parameters:

caption, prompt, default: expressions of type TEXT

more...

less...

The INPUT() function is used to bring up an input dialog box ready for the user to enter a TEXT string in its edit box. INPUT() returns the value entered by the user.

caption is the title of the dialog box. If omitted, a default is used.

prompt is the text that prompts the user to enter a string in the edit box.

default is the string that appears in the edit box when the dialog box is displayed. If omitted, the edit box is empty.

Note: If the user chooses the "Cancel" button in the input dialog, script execution is terminated.
Sample:
VAR forename TEXT, surname TEXT

LET forename=INPUT('Please enter your first name')
LET surname=INPUT('Surname', 'Please enter your last name')

MSGBOX ("Hello, "+forename+' '+surname+'!')
BYTE ISHEX(value)
Parameters:

value: an expression of type TEXT

more...

less...

Use the ISHEX() function to determine whether the TEXT value is a valid hexadecimal number (that is value solely consists of hexadecimal digits, it may optionally be prefixed by "0x"), max. 64 bits. If value is a valid hexadecimal number, 1 is returned, otherwise 0 is returned.
See also: HEX2NUM(), ISNUMBER().
Sample:
VAR inp TEXT

REPEAT
  inp=INPUT('Enter a hexadecimal value')
  IF not ISHEX(inp)
    MSGBOX (inp+" is not a valid hexadecimal number!")
  ENDIF
UNTIL ISHEX(inp)
BYTE ISNUMBER(value)
Parameters:

value: an expression of type TEXT

more...

less...

Use the ISNUMBER() function to determine whether the TEXT value is a valid numeric representation either in decimal (e.g. '100'), hexadecimal (e.g. '0xff') or octal (e.g. '755o') notation (max. 64 bits wide). If value is a valid number, 1 is returned, otherwise 0 is returned.
See also: ISHEX().
Sample:
VAR inp TEXT

REPEAT
  inp=INPUT('Enter a number')
  IF not ISNUMBER(inp)
    MSGBOX (inp+" is not a number!")
  ENDIF
UNTIL ISNUMBER(inp)
DWORD MSGBOX(message [, flags [, title]])
Parameters:

message: expression of type TEXT
flags: optional expression of type DWORD
title: optional expression of type TEXT

more...

less...

MSGBOX() opens a dialog displaying the text message.

The optional flags parameter tells Windows to change the behaviour and/or appearance of the dialog (see MSGBOX flags).

MSGBOX() returns the value of the button the user has selected:
  • IDOK (= 1): "OK" button has been selected
  • IDCANCEL (= 2): "Cancel" button has been selected
  • IDABORT (= 3): "Abort" button has been selected
  • IDRETRY (= 4): "Retry" button has been selected
  • IDIGNORE (= 5): "Ignore" button has been selected
  • IDYES (= 6): "Yes" button has been selected
  • IDNO (= 7): "No" button has been selected
  • IDTRYAGAIN (= 10): "Try Again" button has been selected
  • IDCONTINUE (= 11): "Continue" button has been selected

The optional title parameter modifies the title bar caption of the message dialog.
See also: MSGBOX command.
Sample:
INCLUDE 'def.mps'

VAR btn BYTE

btn=MSGBOX('Click a button', MB_CANCELTRYCONTINUE OR MB_ICONASTERISK)

IF btn==IDCANCEL
  MSGBOX "'Cancel' button has been selected"
ELSE
  IF btn==IDCONTINUE
    MSGBOX "'Continue' button has been selected"
  ELSE
    MSGBOX "'Retry' button has been selected"
  ENDIF
ENDIF
TEXT PARAMS(index)
Parameters:

index: expression of type DWORD

more...

less...

The PARAMS() function returns the contents of the parameter #index (first parameter is at index 0) passed to the script when it's started by a Tools Menu item.
See also: PARAM_COUNT special variable.
Sample:
= save this script under c:\script1.mps
= start of script 1

= execute script 2 and pass to parameters to it
= parameters are separated by blanks or comma
= multiple parameters enclosed in double quotes are used as single parameters
!CMD.ToolsExecuteScript "c:\\script2.mps", '"First argument", "Second argument"'

END

= end of script 1

= save this script under c:\script2.mps
= start of script 2

NUMBER_RADIX=10
NUMBER_PREFIX=''
NUMBER_SUFFIX=''

VAR lp DWORD, param TEXT

= show all parameters
lp=0
WHILE lp < PARAM_COUNT
  param=PARAMS(lp)
  MSGBOX ("Parameter "+TEXT(lp+1)+": "+param)
  INC lp, 1
ENDWHILE

END

= end of script 2
QWORD POSITIONS(index)
Parameters:

index: expression of type QWORD

more...

less...

The POSITIONS() function returns the value of the entry #index in the Position List (first entry is at index 0, an index value of -1 returns the value of the entry that has the focus.)
See also: POSITION_COUNT special variable, POSITION_ADD(), POSITION_SELECTED().
Sample:
= show the value of the currently focused entry in the position list
VAR val QWORD

val=POSITIONS(-1)

IF (val == -1)
  ERROR "No entry selected in the position list"
ELSE
  MSGBOX ("Value of the focused entry in the position list: "+TEXT(DWORD(val)))
ENDIF
DWORD POSITION_ADD(value [, length])
Parameters:

value, length: expressions of type QWORD

more...

less...

The POSITION_ADD() function is used to add a position value to the Position List. The optional parameter length is used to add a selection length. The function returns the index of the new entry in the Position List.
See also: POSITION_COUNT special variable, POSITIONS(), POSITION_SELECTED().
Sample:
= add an entry to the position list and select it
VAR index DWORD, wasselected BYTE, newpos_s TEXT

= query a value to be added to the position list
newpos_s=INPUT("Enter a position value to be added to the position list")

IF (newpos_s == ""):END:ENDIF

index=POSITION_ADD(QWORD(newpos_s))

= select and focus the newly added item
wasselected = POSITION_SELECTED(index, 1, 1)
BYTE POSITION_SELECTED(index [, doselect [, dosetfocus]])
Parameters:

index: an expression of type QWORD
doselect, dosetfocus: optional expressions of type BYTE

more...

less...

The POSITION_SELECTED() function is used to tell whether entry #index of the Position List is currently selected. The function returns 1 if the entry is selected and 0 otherwise (the first entry is at index 0, an index value of -1 acts on the entry that has the focus.)

The optional doselect parameter can be used to change the entry's selection state (1 selects the item, 0 deselects it).

The optional dosetfocus parameter, when set to 1, makes that entry the focused entry in the position list.
See also: POSITION_COUNT special variable, POSITIONS(), POSITION_ADD().
Sample:
= add an entry to the position list and select it
VAR newpos QWORD, index DWORD, wasselected BYTE

= query a value to be added to the position list
newpos=QWORD(INPUT("", "Enter a position value to be added to the position list","-1"))

IF (newpos < 0):END:ENDIF

index=POSITION_ADD(newpos)

= select and focus the newly added position
wasselected = POSITION_SELECTED(index, 1, 1)
QWORD QWORD(expr)
Parameters:

expr: an expression

more...

less...

The QWORD() function is used to convert the expression expr to the QWORD data type. As QWORD is a signed numeric data type (the only one in Tiny Hexer script), it can only store 63 bits of data though it is a 64 bits wide data type.

If expr is a numeric or CHAR expression, the lowest 63 bits of its value and its sign are returned.

If expr is of type TEXT, Tiny Hexer tries to convert the text string to a number. If conversion fails, an error is raised. If conversion succeeds, the lowest 63 bits of the converted number and its sign are returned are returned.
See also: Data types, BYTE(),CHAR(), DWORD(), TEXT(), WORD().
Sample:
VAR inp TEXT

REPEAT
  REPEAT
    inp = INPUT('', 'Enter a negative integral number',  '-1')
  UNTIL ISNUMBER(inp)
UNTIL (QWORD(inp) < 0)
DWORD RANDOM(max)
Parameters:

max: an expression of type DWORD

more...

less...

The RANDOM() function returns a random number within the range 0..max-1.
Sample:
= decimal number to text
LET NUMBER_RADIX = 10
LET NUMBER_PREFIX = ''
LET NUMBER_SUFFIX = ''

MSGBOX "Guess a number game", 64

VAR number BYTE, entered BYTE

LABEL start

= randomly choose a number between 1 and 10
LET number = RANDOM(10)+1

LABEL loop

LET entered = BYTE(INPUT('Enter a number between 1 and 10'))
IF entered == number
  MSGBOX 'Right!'
ELSE
  IF number < entered
    MSGBOX ('My number is less than '+TEXT(entered))
  ELSE
    MSGBOX ('My number is greater than '+TEXT(entered))
  ENDIF
  GOTO loop
ENDIF

GOTO start
DWORD SHELL(program [, parameters [, show [, directory [, output]]]])
Parameters:

program, parameters, directory: expressions of type TEXT
show: an expression of type DWORD
output: an expression of type VARREF

more...

less...

The SHELL() function is used to execute the external application program. Script execution is always stopped until program has finished. SHELL() returns the exit code of the program, if it cannot be executed, 0xFFFFFFFF is returned.

Optionally the command line arguments parameters can be passed to program.

Additionally you can tell Tiny Hexer Script to show or hide the external application using the show parameter (SW_HIDE, SW_SHOW...)

The optional directory parameter tells Windows to set program's current directory.

The optional output parameter is a reference to a TEXT variable that will contain the output of program after its execution.
See also: SHELL command.
Sample:
VAR exitcode DWORD num DWORD inp TEXT fname TEXT

REPEAT
  inp=INPUT('Enter an exitcode')
UNTIL ISNUMBER(inp)

num=DWORD(inp)

NUMBER_RADIX=10
NUMBER_PREFIX=''
NUMBER_SUFFIX=''

VAR f FILE
= create a temp. batch file
fname=ENVPARSE('%temp%')+'\shelltest1.bat'
f=FILEOPEN(fname,'c')

FILEWRITE f, ('@echo Exiting with code '+TEXT(num)+" after key press\n\r")
FILEWRITE f, "@pause\n\r"
FILEWRITE f, ('@exit '+TEXT(num)+"\n\r")
FILECLOSE f

= run the created batch
exitcode=SHELL(fname)

FILEDELETE (fname)

= show the exitcode
MSGBOX ('Exitcode of '+fname+': '+TEXT(exitcode))
QWORD TAG_LEN(ref)
Parameters:

ref: an expression of type VARREF

more...

less...

The TAG_LEN() function returns the length tag of the variable referenced by ref.

If the referenced variable is not tagged, -1 is returned.
See also: Variable Tagging, COPYTAGS command, TAGVAR command, TAG_POS(), OPTION READTAGS directive.
Sample:
= enable variable tagging
OPTION READTAGS, 1

VAR f FILE, t TEXT, msg TEXT

= open tiny hexer itself
f=FILEOPEN(ENVPARSE('%apppath%\mpth.exe'),'r')

= locate a specific position
FILESEEK f, 507634

= read text from file with automatic tagging
FILEREAD f, t, 9
= t is now tagged with file position and data length

FILECLOSE f

msg='Data read from file: "'+t+'"'+"\n\r"
CONCAT msg, 'At position: '+TEXT(TAG_POS(@t))+"\n\r"
CONCAT msg, 'Data length: '+TEXT(TAG_LEN(@t))+"\n\r"

MSGBOX msg
QWORD TAG_POS(ref)
Parameters:

ref: an expression of type VARREF

more...

less...

The TAG_POS() function returns the position tag of the variable referenced by ref.

If the referenced variable is not tagged, -1 is returned.
See also: Variable Tagging, COPYTAGS command, TAGVAR command, TAG_LEN(), OPTION READTAGS directive.
Sample:
= enable variable tagging
OPTION READTAGS, 1

VAR f FILE, t TEXT, msg TEXT

= open tiny hexer itself
f=FILEOPEN(ENVPARSE('%apppath%\mpth.exe'),'r')

= locate a specific position
FILESEEK f, 507634

= read text from file with automatic tagging
FILEREAD f, t, 9
= t is now tagged with file position and data length

FILECLOSE f

msg='Data read from file: "'+t+'"'+"\n\r"
CONCAT msg, 'At position: '+TEXT(TAG_POS(@t))+"\n\r"
CONCAT msg, 'Data length: '+TEXT(TAG_LEN(@t))+"\n\r"

MSGBOX msg
TEXT TEXT(expr)
Parameters:

expr: an expression

more...

less...

The TEXT() function is used to convert the expression expr to the TEXT data type.

If expr is a numeric expression, its value is converted to a textual represention; the conversion format depends on the values of the NUMBER_RADIX, NUMBER_PREFIX and NUMBER_SUFFIX special variables.

If expr is of type TEXT or CHAR, a copy of the string is returned.
See also: Data types; NUMBER_RADIX, NUMBER_PREFIX and NUMBER_SUFFIX special variables; BYTE(), CHAR(), DWORD(), QWORD(), WORD().
Sample:
= show different number to text conversions
VAR number WORD txt TEXT

number=64738

= binary (radix 2)
NUMBER_RADIX=2
NUMBER_PREFIX='%'
NUMBER_SUFFIX=''

MSGBOX TEXT(number)

= octal (radix 8)
NUMBER_RADIX=8
NUMBER_PREFIX=''
NUMBER_SUFFIX='o'

MSGBOX TEXT(number)

= octal (radix 8), alternate output format
NUMBER_RADIX=8
NUMBER_PREFIX='0'
NUMBER_SUFFIX=''

MSGBOX TEXT(number)

= decimal (base 10)
NUMBER_RADIX=10
NUMBER_PREFIX=''
NUMBER_SUFFIX=''

MSGBOX TEXT(number)

= decimal (base 10), "alternate" format
NUMBER_RADIX=10
NUMBER_PREFIX='(prefix) '
NUMBER_SUFFIX=' (suffix)'

MSGBOX TEXT(number)

= hexadezimal (radix 16)
NUMBER_RADIX=16
NUMBER_PREFIX='0x'
NUMBER_SUFFIX=''

MSGBOX TEXT(number)

= hexadezimal (radix 16), alternate output format
NUMBER_RADIX=16
NUMBER_PREFIX=''
NUMBER_SUFFIX='h'

MSGBOX TEXT(number)
NUMBER TEXT2DATA(data, index, count)
Parameters:

data: an expression of type TEXT
index, count: expressions of type DWORD

more...

less...

The TEXT2DATA() function is the counterpart of the DATA2TEXT() function. It is used to extract numeric values from tables created by DATA2TEXT().

data contains the binary data values.

index is the index to the data TEXT string, where data extraction starts, multiplied by the count parameter value.

count is the amount of data to be extracted. The type of the data returned by TEXT2DATA() depends on this parameter. This parameter must be either 1 (=Byte), 2 (=Word), 4 (= DWORD) or 8 (= QWORD).
See also: DATA2TEXT().
Sample:
= power of 2 table example
INCLUDE 'def.mps'
NUMBER_RADIX = 10
NUMBER_PREFIX = ''
NUMBER_SUFFIX = ''

VAR ptable TEXT, num QWORD
VAR inp TEXT q QWORD power QWORD
OPTION GLOBALVARS, 1

LET num = 1
LET ptable = ''
LOOP create_table 63

REPEAT
  REPEAT
    REPEAT
      LET inp = INPUT('Enter a number between 0 and 62')
    UNTIL ISNUMBER(inp)
    LET q = QWORD(inp)
  UNTIL (q < 63) AND (q >= 0)

  = power values are stored as QWORD, so QWORD_SIZE must be used
  = to access the correct data
  power = TEXT2DATA(ptable, q, QWORD_SIZE)
  MSGBOX ( '2 ** '+TEXT(q)+' = '+TEXT(power))

UNTIL 0

END

= store the next power of 2 as QWORD in ptable
@@create_table
CONCAT ptable, DATA2TEXT(QWORD(num))
INC num, num
RETURN
TEXT TEXTCHOP(string [, flags])
Parameters:

string, flags: expressions of type TEXT

more...

less...

TEXTCHOP() is used to remove preceding and/or trailing whitespaces from a string (whitespaces are characters from 0x00..0x20).

string is the text expression to be chopped.

The optional flags parameter tells the function where to remove whitespaces:
  • "pt" (default): remove preceding and trailing whitespaces
  • "p": remove preceding whitespaces only
  • "t": remove trailing whitespaces only
Sample:
VAR in TEXT, out TEXT

= generate a string with garbage at beginning and end
in = "\t STRING\n\r"
= in: (0x09)(0x20)"STRING"(0x0a)(0x0d)

out = TEXTCHOP(in) := (or out = TEXTCHOP(in,"pt"))
= out now contains "STRING"

out = TEXTCHOP(in, "p")
= out now contains "STRING"(0x0a)(0x0d)

out = TEXTCHOP(in, "t")
= out now contains (0x09)(0x20)"STRING"
TEXT TEXTCOPY(string, start [, count])
Parameters:

string: an expression of type TEXT
start, count: expressions of type DWORD

more...

less...

The TEXTCOPY() function returns a part of the value of string.

start is the index to the first character of string to copy (the first char is at index 1, not 0!).

count is the amount of characters to copy. If this parameter is omitted, all characters from start up to the last character are copied.
See also: TEXTLEN(), TEXTPOS().
Sample:
var txt1 TEXT, txt2 TEXT
txt1="This is a text"

txt2=TEXTCOPY(txt1, 6, 2)
= txt2 now contains the text "is"

MSGBOX txt2
DWORD TEXTLEN(string)
Parameters:

string: an expression of type TEXT

more...

less...

TEXTLEN() returns the length (in characters) of string.
See also: TEXTCOPY(), TEXTPOS().
Sample:
var inp TEXT

REPEAT
  inp=INPUT('Enter a text consisting of exactly six characters')
UNTIL TEXTLEN(inp) == 6
TEXT TEXTLOWER(string)
Parameters:

string: an expression of type TEXT

more...

less...

TEXTLOWER() converts all characters in string to lower case and returns the converted TEXT.
See also: TEXTUPPER().
Sample:
var str TEXT

str="Lower Case"

str=TEXTLOWER(str)
= str is set to "lower case" now

MSGBOX str
DWORD TEXTPOS(substr, string)
Parameters:

substr, string: expressions of type TEXT

more...

less...

TEXTPOS() returns the index of the first occurance of the string substr in string. If substr is not contained in string, 0 is returned.
See also: TEXTCOPY(), TEXTLEN().
Sample:
var inp TEXT

REPEAT
  inp=INPUT('Enter a string that contains the text "hex"')
UNTIL TEXTPOS("hex",inp) > 0
TEXT TEXTUPPER(string)
Parameters:

string: an expression of type TEXT

more...

less...

TEXTUPPER() converts all characters in string to upper case and returns the converted TEXT.
See also: TEXTLOWER().
Sample:
var str TEXT

str="Upper Case"

str=TEXTUPPER(str)
= str is set to "UPPER CASE" now

MSGBOX str
BYTE TYPEOF(expr)
Parameters:

expr: an expression

more...

less...

TYPEOF() returns the data type of expr.

An expression has one of the following data types:
  • CHAR_DATA (=1): CHAR data type
  • BYTE_DATA (=2): BYTE data type
  • WORD_DATA (=3): WORD data type
  • DWORD_DATA (=4): DWORD data type
  • QWORD_DATA (=5): QWORD data type
  • TEXT_DATA (=6): TEXT data type
  • FILE_DATA (=7): FILE data type
  • VARREF_DATA (=8): VARREF data type
See also: Data Types.
Sample:
= show data type example
INCLUDE 'def.mps'

VAR c CHAR, b BYTE, w WORD, d DWORD, q QWORD, t TEXT, f FILE, r VARREF, n NONE

CALL dt @c : CALL dt @b : CALL dt @w : CALL dt @d
CALL dt @q : CALL dt @t : CALL dt @f : CALL dt @r : CALL dt @n

END

VAR type BYTE, ref VARREF

@@dt

POP ref
LET type = TYPEOF(DEREF(ref))

IF type == CHAR_DATA
  MSGBOX 'Char data'
ELSE
  IF type == BYTE_DATA
    MSGBOX 'Byte data'
  ELSE
    IF type == WORD_DATA
      MSGBOX 'Word data'
    ELSE
      IF type == DWORD_DATA
        MSGBOX 'DWord data'
      ELSE
        IF type == QWORD_DATA
          MSGBOX 'QWord data'
        ELSE
          IF type == TEXT_DATA
            MSGBOX 'TEXT String data'
          ELSE
            IF type == FILE_DATA
              MSGBOX 'File data'
            ELSE
              IF type == VARREF_DATA
                MSGBOX 'Variable reference'
              ELSE
                MSGBOX 'Empty data'
              ENDIF
            ENDIF
          ENDIF
        ENDIF
      ENDIF
    ENDIF
  ENDIF
ENDIF

RETURN
WORD WORD(expr)
Parameters:

expr: an expression

more...

less...

The WORD() function is used to convert the expression expr to the WORD data type.

If expr is a numeric or CHAR expression, the lowest 16 bits of its value are returned.

If expr is of type TEXT, Tiny Hexer tries to convert the text string to a number. If conversion fails, an error is raised. If conversion succeeds, the lowest 16 bits of the converted number are returned.
See also: Data types, BYTE(), CHAR(), DWORD(), QWORD(), TEXT().
Sample:
= convert a text to a word number
VAR inp TEXT w WORD

REPEAT
  inp = INPUT('Enter a numeric value')
UNTIL ISNUMBER(inp)

LET w = WORD(inp)

= output hexadecimal
MSGBOX ('The number you entered was (hex): '+TEXT(w))


Tiny Hexer Script: Expressions

Expressions in Tiny Hexer Script are constructs which return values.

Expressions can either consist of simple literals or variables of different data types or of complex constucts which are build using parenthesis, literals, operators and functions.
Sample expressions:
var1                := variable
@var1               := variable reference
224                 := BYTE literal
0xE0                := hexadecimal BYTE literal
'Hello, world'      := TEXT literal
"Hello, world\n\r"  := TEXT literal
FILESIZE(f)         := function call
a * b               := product of a and b
var1 / (1 - var1)   := quotient of var1 and (1 - var1)
var1 != 2           := TRUE/FALSE condition (BYTE data type)
not var1            := negation of a TRUE/FALSE condition


Tiny Hexer Script: Operators

Operators in Tiny Hexer Script are used to construct expressions.
  • Overview
  • Numeric operators
  • TEXT operators
  • Relational operators
  • Reference operator @
  • Operator precedence

Overview

Operators are used to build expressions by taking an action on one or two parameters. Those parameters are called operands. Operators taking one operand are unary operators, operators taking two operands are called binary.

Unary operators (like @, - and not) always precede their operand (e.g. -3).

Binary operators (like *, mod or !=) are always placed between their operands (e.g. 3 * 4).

The operators + and - can be either unary (e.g. -3) or binary (e.g. 4 - 3).

The behaviour of some of the operators depends on the data types of their operands (e.g. "ab" * 3 results in "ababab", 4 * 3 results in 12).

Numeric operators

Numeric operators are used to do numeric calculations.

The following binary numeric operators exist in Tiny Hexer Script:

  • +: calculate the sum of the operands (3 + 4 → 7)
  • -: calculate the difference of the operands (4 - 3 → 1)
  • *: calculate the product of the operands (3 * 4 → 12)
  • /: calculate the integral quotient of the operands (10 / 2 → 5)
  • MOD: calculate the remainder of the integral quotient of the operands (8 MOD 3 → 2)
  • AND: bitwise and of the operands (%1100 AND %0101 → %0100)
  • OR: bitwise or of the operands (%1100 OR %0101 → %1101)
  • XOR: bitwise exclusive or of the operands (%1100 XOR %0101 → %1001)
  • <<: shift operand1 operand2 bits to the left (%0011 << 2 → %1100)
  • >>: shift operand1 operand2 bits to the right (%1100 >> 2 → %0011)

The following unary numeric operators exist in Tiny Hexer Script:

  • +: returns the value (+4 → 4)
  • -: negates the sign of the value (x=-4:-x → 4)
  • NOT: returns TRUE (=1) if the operand equals to 0, FALSE (=0) otherwise (NOT 0 → 1, NOT 7 → 0)

TEXT operators

TEXT operators are used to modify TEXT string values.

The following binary TEXT operators exist in Tiny Hexer Script:

  • +: concats both TEXT operands and returns the resulting TEXT ("foo" + "bar" → "foobar")
  • *: concats the TEXT operator1 operator2 times ("foo" * 4 → "foofoofoofoo")

Relational operators

Relational operators are used to compare their two operands. Both operands must be of compatible data types, but FILE and VARREF types cannot be compared.

If comparsion succeeds, TRUE (=1) is returned, FALSE (=0) otherwise.

The following binary relational operators exist in Tiny Hexer Script:

  • ==: equals operand1 to operand2? (4 == 3 → 0)
  • !=: do operand1 and operand2 differ? ("foo" != "bar" → 1)
  • <=: is operand1 less than or equal to operand2? (4 <= 3 → 0)
  • >=: is operand1 geater than or equal to operand2? (4 >= 3 → 1)
  • <: is operand1 less than operand2? (4 < 3 → 0)
  • >: is operand1 geater than operand2? (4 > 3 → 1)

The Reference operator @

The unary @ operator returns an expression of type VARREF. Its operand must be a variable. This operator is used to store not only the value of a variable, but a reference to the variable itself. To retrieve the variable that is referenced by a VARREF expression, use the DEREF() function.

Some functions (like FILEREAD()) need VARREF parameters to be able to get directaccess to the variable (e.g. for variable tagging).

If you change the value of the variable that is referenced by a VARREF expression, a DEREF() call always returns the actual value of that variable, not the value that was stored at the time the assignment has been made:

@ sample:
VAR a TEXT b TEXT r VARREF

= assign a value to a
a="foo"

= store the value in b
b=a

= store the variable itself in r
r=@a

= now change the value of a
a="bar"

= b still contains "foo"
MSGBOX b

= r points to a, so the current value of a is shown
MSGBOX DEREF(r)

Operator precedence

In expressions containing multiple operators, the order of operator computation depends on precedence rules. Operators with higher precedence are evaluated before operators with lower precedence. To break those precedence rules, you can use parenthesis:

4 + 3 * 7 → 25. The multiplication (3 * 7) is calculated before the sum (4 + 21), because the * operator has a higher precedence than the + operator.

(4 + 3) * 7 → 49 breaks this rule because the sum is calculated before the product.

Precedences (in descending order, the first operator has the highest precedence):

  • @
  • unary +, unary -, NOT
  • AND, *, MOD, <<, >>, /
  • OR, XOR, +, -
  • ==, !=, <=, >=, <, >


Command Actions

Command Name | Parameters | Description
CMD.BookmarkAdd | - | Add current position to bookmarks
CMD.BookmarkEdit | - | Change stored bookmarks
CMD.CompareCompareEditor | TEXT FileName | Compare the editor file to another open file
CMD.CompareCompareFile | TEXT FileName | Compare the editor file to a file on disk
CMD.CompareCompareSelEditor | TEXT FileName | Compare the editor's selection to a another open file
CMD.CompareCompareSelFile | TEXT FileName | Compare the editor's selection to a file on disk
CMD.CompareNext | - | Navigate to the next block of differences
CMD.ComparePrevious | - | Navigate to the previous block of differences
CMD.CompareReset | - | Clear the comparison result buffer
CMD.CompareShowDiffs | BYTE DoHilight | Highlight bytes that differed in comparison
CMD.DiskFirstSector | - | Load first sector from disk
CMD.DiskGotoSectorPosition | QWORD SectorNumber | Load a specific sector from disk
CMD.DiskLastSector | - | Load last sector from disk
CMD.DiskNextSector | - | Load next sector from disk
CMD.DiskOpenDrive | TEXT PartitionOrDrive [, DWORD AmountOfSectors] | Open a hard disk, floppy or CDRom
CMD.DiskPreviousSector | - | Load previous sector from disk
CMD.DiskWriteSector | - | Write changes back to disk
CMD.EditAddToPosList | - | Add the current position to the position list
CMD.EditConvert | TEXT TranslationFrom, TEXT TranslationTo | Convert Data
CMD.EditCopy | - | Copy selection to clipboard
CMD.EditCut | - | Cut selection to clipboard
CMD.EditDeleteNibble | - | Delete a half byte (nibble) at the current position
CMD.EditFindNext | - | Repeat most recent find action
CMD.EditFindReplace | TEXT FindReplaceWhat, BYTE DoIgnoreCase, BYTE DoFindTextOrRegEx [, TEXT Wildcard [, TEXT Replacement, BYTE DoReplaceText, BYTE DoReplaceAll]] | Find (and replace) text or data; if DoFindTextOrRegEx=2, do a regular expression search.
CMD.EditFindStore | TEXT DataToFind, BYTE DoIgnoreCase, BYTE DoFindTextOrRegEx [, TEXT Wildcard [, BYTE DoSearchWholeDisk, [BYTE DoOverwriteCurrentList]]] | Find all occurences of a data in a document and store the results in the position list. If DoFindTextOrRegEx=2, do a regular expression search.
CMD.EditGoto | DWORD Position | Goto position
CMD.EditInsertNibble | - | Insert a half byte (nibble) at the current position
CMD.EditPaste | - | Paste clipboard contents
CMD.EditRedo | - | Revoke last undo
CMD.EditSelect | DWORD SelStart, DWORD SelEnd | Enter start and end position of the selection
CMD.EditSelectAll | - | Select all
CMD.EditUndo | - | Undo last modification
CMD.FileClose | - | Close the current window
CMD.FileCloseAll | - | Close all editor windows
CMD.FileExit | - | Close
CMD.FileExport | TEXT ExportScriptName, TEXT FileName [, BYTE DoOnlySelection, BYTE DoToClipboard] | Export file or current selection to disk or clipboard
CMD.FileImport | TEXT FileName, TEXT ImportScriptName | Import data from a file in a specific format
CMD.FileInsertFile | TEXT FileName | Insert the contents of a different file
CMD.FileNew | - | New file
CMD.FileOpen | TEXT FileName | Open file
CMD.FileOpenGroup | TEXT GroupFileName | Open a group of files
CMD.FilePrint | - | Print Data
CMD.FilePrintSetup | - | Change printer options
CMD.FileReload | [BYTE DoSkipConfirmation] | Reload the current file from disk
CMD.FileReopenCleanup | - | Remove not existing files from this menu
CMD.FileSave | - | Save file
CMD.FileSaveAs | TEXT FileName | Save file under a different name
CMD.FileSaveGroup | TEXT GroupFileName[, BYTE DoSaveAllOpenFiles] | Save a file group. If DoSaveAllFiles is set to 1, you are not prompted for selection of the files in the group but all open files are put in the group
CMD.FileSaveSelection | TEXT FileName | Save the current selection to disk
CMD.FileStatistics | [TEXT ExportFileName[, BYTE DoCloseDialog]] | Show file statistics and possibly export them to a RTF file
CMD.HelpAbout | - | Show About Box
CMD.HelpIndex | - | Show help index
CMD.HelpLookForUpdates | - | Look for available updates on www.mirkes.de
CMD.HelpScriptReference | - | Show the Tiny Hexer Script reference help index
CMD.HelpVersionHistory | - | Show Tiny Hexer's version history
CMD.OptionsCustomizeTB | - | Add or delete buttons on the tool bar
CMD.OptionsEditCustomTranslationTable | - | Edit custom translation table
CMD.OptionsEditorSettings | - | Change current editor window's properties
CMD.OptionsGlobalSettings | - | Change global settings
CMD.OptionsLoad | TEXT FileName | Restore previously saved settings
CMD.OptionsSave | TEXT FileName | Save current settings to file
CMD.PosListCopy | - | Copy the items selected in the position list to the clipboard
CMD.PosListDeleteSelected | - | Remove all selected items from the position list
CMD.PosListLoad | TEXT FileName | Load the given file into the position list
CMD.PosListPrint | - | print the contents of the position list
CMD.PosListSave | TEXT FileName | Save the contents of the position list to file
CMD.PosListSelectAll | - | Select all items in the position list
CMD.PosListShiftSelected | QWORD ShiftValue | Modify the value of the selected entries in the position list
CMD.ProcessReadMemory | - | Open the Read Process Memory dialog
CMD.ProcessWriteMemory | - | Show the Write Process Memory dialog
CMD.StructCancelUpdate | - | Structure Viewer: Cancel script execution
CMD.StructCopy | - | Structure Viewer: Copy to clipboard
CMD.StructHelp | - | Structure Viewer: Open the help file
CMD.StructLoadScript | TEXT FileName | Structure Viewer: Load a structure script
CMD.StructNew | - | Structure Viewer: Clear the current script
CMD.StructPrint | - | Structure Viewer: Print contents
CMD.StructSaveOutput | TEXT FileName | Structure Viewer: Save the text to a file
CMD.StructSelectAll | - | Structure Viewer: Select whole text
CMD.StructUpdate | - | Structure Viewer: Update structure
CMD.ToolsConfigure | - | Configure the toolbox
CMD.ToolsExecuteScript | TEXT ScriptFileName [, TEXT Parameters] | Load and execute an Tiny Hexer script
CMD.ToolsPosList | BYTE DoShow | Show/Hide the position list
CMD.ToolsStructureViewer | BYTE DoShow | Show/Hide the structure viewer
CMD.ToolsValueEditor | BYTE DoShow | Show/Hide the value editor
CMD.ViewEditorOffsetDec | - | Decimal offset
CMD.ViewEditorOffsetHex | - | Hexadecimal offset
CMD.ViewEditorOffsetNone | - | No offset
CMD.ViewEditorOffsetOct | - | Octal offset
CMD.ViewNumberDec | - | Show Decimal numbers
CMD.ViewNumberHex | - | Show Hexadecimal numbers
CMD.ViewNumberOct | - | Show Octal numbers
CMD.ViewReadOnlyView | BYTE DoViewReadOnly | View files, do not allow to edit
CMD.ViewSynchronize | BYTE DoSynchronize | TEXT WindowToSynchronize [, QWORD SynchronizeOffset] | Start/stop editor view synchronization
CMD.ViewTranslationUnicodeBE | BYTE DoViewUnicode | Switch unicode (Big Endian) on/off
CMD.ViewTranslationUnicodeLE | BYTE DoViewUnicode | Switch unicode (Little Endian) on/off
CMD.ViewWindowBar | BYTE DoShow | Toggle the window bar
CMD.WindowCascade | - | Cascade windows
CMD.WindowTileH | - | Tile windows horizontally
CMD.WindowTileV | - | Tile windows vertically


MSGBOX flags

The flags parameter of the MSGBOX command/function can be a combination of the following values:
Flag | Value | Description
MB_OK | 0x00 | The message box contains one push button: OK. This is the default.
MB_OKCANCEL | 0x01 | The message box contains two push buttons: OK and Cancel.
MB_ABORTRETRYIGNORE | 0x02 | The message box contains three push buttons: Abort, Retry, and Ignore.
MB_YESNOCANCEL | 0x03 | The message box contains three push buttons: Yes, No, and Cancel.
MB_YESNO | 0x04 | The message box contains two push buttons: Yes and No.
MB_RETRYCANCEL | 0x05 | The message box contains two push buttons: Retry and Cancel.
MB_CANCELTRYCONTINUE | 0x06 | Microsoft® Windows® 2000/XP: The message box contains three push buttons: Cancel, Try Again, Continue. Use this message box type instead of MB_ABORTRETRYIGNORE.
MB_ICONHAND MB_ICONERROR MB_ICONSTOP | 0x10 | A stop-sign icon appears in the message box.
MB_ICONQUESTION | 0x20 | A question-mark icon appears in the message box.
MB_ICONEXCLAMATION MB_ICONWARNING | 0x30 | An exclamation-point icon appears in the message box.
MB_ICONASTERISK MB_ICONINFORMATION | 0x40 | An icon consisting of a lowercase letter i in a circle appears in the message box.
MB_DEFBUTTON1 | 0x00 | The first button is the default button.
MB_DEFBUTTON2 | 0x0100 | The second button is the default button.
MB_DEFBUTTON3 | 0x0200 | The third button is the default button.
MB_DEFBUTTON4 | 0x0300 | The fourth button is the default button.
MB_RIGHT | 0x00080000 | The text is right-justified.


Properties

Properties common to all files except Structure Viewer Browser window ('::Browser' file):
Property Name | Data Type | Description
Position | DWORD | File's position pointer
Size | DWORD | File's size
Properties of Structure Viewer Browser window ('::Browser' file):
Property Name | Data Type | Description
AcceptTags | BYTE | If set to 1, you can write HTML Tags to the browser window. If Set to 0 (default), HTML special chars are converted so they are displayed literally (e.g. '<' is converted to '&lt;')
Properties of Hexeditor windows ('::New', '::Editor', '::Current', '::<filename>' files) :
Property Name | Data Type | Description
AbsolutePosition | QWORD | If a disk/partition is edited, this is the absolute position of the cursor on the whole disk/partition
AbsoluteSize | QWORD | If a disk/partition is edited, this is the size of the whole disk/partition, not the size of the part being edited (readonly)
BackupExtension | TEXT | Extension of the Backup Filename (readonly)
BytesPerBlock | BYTE | Number of bytes per block displayed by the editor
BytesPerColumn | BYTE | Number of bytes per column displayed by the editor
BytesPerRow | BYTE | Number of bytes per row displayed by the editor
Colors.Background | DWORD | Editor's background color (blue/green/red: 0xff0000 = blue)
Colors.ChangedBackground | DWORD | Editor's background color of modified data (Overtype mode only)
Colors.ChangedText | DWORD | Editor's text color of modified data (Overtype mode only)
Colors.CurrentOffset | DWORD | Editor's text color of the current line (Offset pane)
Colors.CurrentOffsetBackground | DWORD | Editor's background color of the current line (Offset pane)
Colors.CursorFrame | DWORD | Editor's color of the cursor frame
Colors.EvenColumn | DWORD | Editor's text color of data in even columns (Hex pane)
Colors.OddColumn | DWORD | Editor's text color of data in odd columns (Hex pane)
Colors.Offset | DWORD | Editor's text color ine the offset pane
Colors.OffsetBackGround | DWORD | Editor's background color ine the offset pane
CurrentValue | QWORD | Value of the Byte at the current cursor position, -1 if the editor has no data (readonly)
FileName | TEXT | Name of the file loaded in the editor (readonly)
FillByte | BYTE | This data is used to fill newly allocated memory when enlarging a data file
FixedSize | BYTE | 1 if the filesize is fixed (e.g. when editing disk sectors or memory blocks), 0 otherwise
Font.Color | DWORD | Editor's text color
Font.Name | TEXT | Editor's text Font name
Font.Size | DWORD | Editor's text Font size
HasFile | BYTE | 1 if the data in the editor has been loaded from a file, 0 otherwise (readonly)
InCharField | BYTE | 1 if the cursor is located in the character pane, 0 if located in the hex pane
Modified | BYTE | 1 if the data in the editor has been modified, 0 otherwise
PrintFont.Color | DWORD | Text color when printing
PrintFont.Name | TEXT | Text Font name when printing
PrintFont.Size | DWORD | Text Font size when printing
PrintOptions.MarginBottom | DWORD | Bottom Margin when printing (millimeters)
PrintOptions.MarginLeft | DWORD | Left Margin when printing
PrintOptions.MarginRight | DWORD | Right Margin when printing
PrintOptions.MarginTop | DWORD | Top Margin when printing
PrintOptions.PageFooter | TEXT | Page Footer text
PrintOptions.PageHeader | TEXT | Page Header Text
ReadOnlyFile | BYTE | 1 if the file has been opened readonly, 0 otherwise
SelCount | DWORD | Number of bytes currently selected
SelStart | DWORD | Index of first byte of the currently selected data


Read Process Memory: No data could be read from the process

None of the process' memory blocks could be accessed. On Windows NT/2000/XP you might need administrative privileges to get access to some processes. Even as an administrator, some (system) processes might be completely unaccessible from other processes.
See also: Read Process Memory dialog.


Read Process Memory: Size of data to search for must be a multiple of Bytes per unit

You cannot search in odd-sized memory blocks if the Unicode box is checked. Please uncheck that box.
See also: Read Process Memory dialog.


Read Process Memory: Data not found

The data you searched for could not be found in the process's memory. You can search again by clicking the Find button after selecting the first memory block in the Memory Block List. You might additionally switch the Unicode checkbox if you are searching for text.
See also: Read Process Memory dialog.


Read Process Memory: The data could not be found in the current memory block

The data you searched for could not be found in the process's selected memory block.

You have the following choices:
  • Yes: Search in the memory block following the currently selected block
  • No: Stop searching
  • Yes to All: Search in all process's memory blocks following the selected one
See also: Read Process Memory dialog.


Options: This hotkey is already used

The menu shortcut you entered is already used by another command. Assigning a shortcut to more than one menu command leads to unpredictable shortcut handling.

Please choose a different shortcut.
See also: Options dialog.


Save changes

The file to be closed has been modified but not yet saved.

You have the following choices:
  • Yes: Save the file to disk
  • No: Do not save the file (so modifications are lost)
  • Cancel: Do not close the file


No differences found, but the file is larger than the data to compare

Though the first sizeof(editor file) bytes of the disk file's data match the editor data, the disk file is larger than the editor file, so they do not contain the same data.
See also: File Comparison dialog.


No differences found, but the file is smaller than the data to compare

Though the first sizeof(disk file) bytes of the editor file's data match the disk file data, the disk file is smaller than the editor file, so they do not contain the same data.
See also: File Comparison dialog.


The file is smaller than the data to compare

Editor and disk file contain different data and the file on disk is smaller than the compared editor data.
See also: File Comparison dialog.


The file is larger than the data to compare

Editor and disk file contain different data and the file on disk is larger than the compared editor data.
See also: File Comparison dialog.


No more blocks of differences

The cursor is already located in the last consecutive block of different bytes.
See also: File Comparison dialog.


No previous block of differences

The cursor is already located in the first consecutive block of different bytes.
See also: File Comparison dialog.


File is already open. Open it again as unnamed file

The file you chose to open in Tiny Hexer is already opened. A file can only be opened once at a time in Tiny Hexer.

You have the following choices:
  • Yes: Open the file's data in a new editor window but detach it from the original disk file.
  • No: Do not open the file again but activate the already opened file.
  • Cancel: Stop opening files.


Do you really want to write to disk?

You are about to overwrite data on a disk or partition. The operating system likely may have changed the data on disk while you modified it in Tiny Hexer. So writing back the data to disk may lead to an inconsistent file system, that is all data on that partition might get lost.

When you try to overwrite a drive's partition table with incorrect data, all data on that disk is lost!

You have the following choices:
  • OK: Overwrite the data on disk with the editor's data.
  • Cancel: Do not write the editor's data back to disk.
See also: File/Disk menu.


Size of data to search for must be a multiple of Bytes per unit

This error message is displayed when you try to search for odd-sized data when the editor is in unicode mode.


Size of replacement data must be a multiple of Bytes per unit

This error message is displayed when you try to replace with odd-sized data if the editor is in unicode mode.


Find: The data has not been found in the currently edited sector(s)

The data you searched for could not be found in the disk sector(s) loaded into to editor.

You have the following choices:
  • Yes: Repeat the search in the following range of sectors
  • No: Stop searching
  • Yes to All: Repeat the search in all following sectors
Hint: To search for data crossing sector boundaries, you should at least load two sectors at once into the editor. If more than one sector is edited at a time, choosing 'Yes' or 'Yes To All' forces Tiny Hexer to load the last currently edited sector again (e.g. sectors 0-1 (two sectors at once), then 1-2, 2-3 and so on).
See also: Open Drive/Partition dialog.


Overwrite the existing position list's data

The position list already contains entries.

You have the following choices:
  • Yes: Clear the position list before adding entries to it.
  • No: Merge the existing entries with the entries found.
  • Cancel: Stop search.


Search whole disk/partition

You are searching for all occurences of data on a disk or partition.

You have the following choices:
  • Yes: Search on the whole disk or partition.
  • No: Only search in the data currently loaded into the editor.
  • Cancel: Stop search.


Do you really want to lose all changes and reload

You have requested to discard all changes in the document that are not yet saved to disk and return the document to the original contents of the associated file.

You have the following choices:
  • Yes: Discard the changes and reload the file from disk
  • No: Do not reload the file from disk


File is not a Structure Viewer script

The script you want to execute in the Structure Viewer seems not be designed for it. Structure Viewer scripts are usually located in the scripts\Structure Viewer directory.

However, if you still want to open this script in the Structure Viewer, please make sure the script contains the line OPTION TARGET, STRUCTUREVIEWER.


Overwrite the existing position list's data

The position list already contains entries.

You have the following choices:
  • Yes: Clear the position list before loading entries from file.
  • No: Merge the existing entries with the entries in the file.
  • Cancel: Stop loading the file's entries.


The file doesn't seem to be a Tiny Hexer configuration file. Load it anyway?

The configuration file to be loaded has either been created by an old version of Tiny Hexer or by another application.

You have the following choices:
  • Yes: Load the settings from this file.
  • No: Do not load the settings from this file.